Emby

Deploy Emby media server.

Ansible hosts group: emby

Variables

Option	Type	Description	Default
cs_emby_docker_tag	string	Emby docker tag	4.10.1.0
cs_emby_container_image	string	Emby container image	{{ cs_vm_artifact_registry_containers_home }}/embyserver
cs_emby_container_name	string	Emby container name	emby
cs_emby_container_dri_list	list	GPU DRI device list	[]
cs_emby_user	string	Dedicated user for Emby (no home, no login)	emby
cs_emby_group	string	Dedicated group for Emby	emby
cs_emby_user_gid	int	GID for the Emby group	1980
cs_emby_user_uid	int	UID for the Emby user	1981
cs_emby_dns_servers	list	DNS servers for Emby	The cluster's DNS servers (from Vault)
cs_emby_media_dir	string	Media directory	/app/emby-media
cs_emby_container_root	string	Single root directory (everything Emby owns)	/app/emby-container-root
cs_emby_container_media_mounts	list	List of media mounts	[]
cs_emby_cluster	string	Cluster name	{{ cs_cluster_name }}
cs_emby_local_subnets	list	Local subnets	The cluster CIDR and VPN CIDR (from Vault)
cs_emby_local_network_addresses	list	Local network addresses	The cluster CIDR and VPN CIDR (from Vault)
cs_emby_restic_cluster_name	string	Restic cluster name	{{ cs_emby_cluster }}
cs_emby_restic_node_name	string	Restic backup node name	{{ inventory_hostname }}
cs_emby_restic_repo_name	string	Restic repository name	emby

First deployment

Emby creates system.xml under cs_emby_container_root only after its first-run setup. On a host without that file the play starts the container, then stops with an error that points at the initial setup page (http://<host IP>:<internal HTTP port>/web/index.html). Complete the setup there, then run the play again. Once system.xml exists the play configures its ports, HTTPS certificate, local networks, and plugins.

Hardware acceleration

• Intel/AMD VAAPI is exposed through cs_emby_container_dri_list (DRI devices).
• The play attaches NVIDIA GPUs automatically: it runs nvidia-smi on the host and, when that succeeds (driver installed and loaded, see the patch_nvidia stage), starts the container with the NVIDIA runtime and all GPUs (device_requests), plus NVIDIA_VISIBLE_DEVICES=all and NVIDIA_DRIVER_CAPABILITIES=compute,video,utility for NVENC/NVDEC. Hosts without a working NVIDIA driver skip these options, and Emby runs unchanged.

Vault configurations

• key: {{ cs_project_code }}/application-deployer/clusters/{{ cs_emby_cluster }}/hosts/{{ inventory_hostname }}/apps/emby/config

{
    "pkcs12_base64": "(Optional) Base64 encoded PKCS#12 certificate",
    "pkcs12_password": "(Optional) PKCS#12 certificate password",
    "internal_https_port": "Internal HTTPS port",
    "public_http_port": "Public HTTP port",
    "public_https_port": "Public HTTPS port",
    "internal_http_port": "Internal HTTP port"
}

Backup

Restic backs up only cs_emby_container_root (Emby's own database/config). cs_emby_media_dir and any cs_emby_container_media_mounts entries sit outside that root and are excluded on purpose: they hold the operator's existing media library, which is stored on and protected by the underlying disks/NAS independently of this repo, not data Emby itself generates.

The {{ cs_emby_container_name }} container is stopped for the duration of the backup and started again afterwards, even if the backup itself fails.

Cleanup (dangerously_cleanup_emby)

Destructive. Only runs when this exact tag is passed explicitly (it is intentionally excluded from the plain emby tag) and permanently deletes Emby's own data on the host:

• Removes the {{ cs_emby_container_name }} Docker container.
• Deletes the UFW allow rules opened for the internal HTTP/HTTPS and public HTTP/HTTPS ports.
• Deletes cs_emby_container_root. cs_emby_media_dir and any cs_emby_container_media_mounts entries are left untouched, since they hold the operator's existing media library, not data Emby itself generates.
• Deletes the {{ cs_emby_user }} user, its home directory, and the {{ cs_emby_group }} group.

Tags

• emby: Deploy Emby media server.
• emby_install: Install Emby.
• emby_restic_backup: Run Restic backup for Emby.
• emby_restic_restore: Restore Emby's data from the latest Restic snapshot.
• dangerously_cleanup_emby: Destructive. Removes the Emby Docker container, closes its UFW ports, and deletes cs_emby_container_root. Never included by the plain emby tag.

Deployment

uv sync --all-extras --all-packages --no-progress
uv --offline run --no-sync --no-progress ansible-galaxy install -r requirements.yml
uv --offline run --no-sync --no-progress ansible-playbook playbook.yml --tags emby