Navidrome

Deploy Navidrome music streaming server.

Ansible hosts group: navidrome

Variables

Option	Type	Description	Default
cs_navidrome_docker_image	string	Navidrome docker image	{{ cs_vm_artifact_registry_containers_home }}/navidrome
cs_navidrome_docker_tag	string	Navidrome docker tag	0.64.2
cs_navidrome_container_name	string	Container name	navidrome
cs_navidrome_group	string	Dedicated group	navidrome
cs_navidrome_user	string	Dedicated user (no home, no login)	navidrome
cs_navidrome_user_gid	int	GID for the Navidrome group	1988
cs_navidrome_user_uid	int	UID for the Navidrome user	1989
cs_navidrome_server_dns	list	DNS servers	The cluster's DNS servers (from Vault)
cs_navidrome_container_root	string	Container root directory	/app/navidrome-container-root
cs_navidrome_media_dir	string	Primary music library directory	/app/navidrome-media
cs_navidrome_cluster	string	Cluster name	{{ cs_cluster_name }}
cs_navidrome_container_media_mounts	list	List of additional music library mounts	[]
cs_navidrome_local_subnets	list	Subnets trusted as the reverse proxy	The cluster CIDR and VPN CIDR (from Vault)
cs_navidrome_restic_cluster_name	string	Restic cluster name	{{ cs_navidrome_cluster }}
cs_navidrome_restic_node_name	string	Restic backup node name	{{ inventory_hostname }}
cs_navidrome_restic_repo_name	string	Restic repository name	navidrome

Vault configurations

• key: {{ cs_project_code }}/application-deployer/clusters/{{ cs_navidrome_cluster }}/hosts/{{ inventory_hostname }}/apps/navidrome/config

{
    "port": "Web UI/API port"
}

Backup

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

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

Cleanup (dangerously_cleanup_navidrome)

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

• Removes the {{ cs_navidrome_container_name }} Docker container.
• Deletes the UFW allow rule opened for the web UI port.
• Deletes cs_navidrome_container_root. cs_navidrome_media_dir and any cs_navidrome_container_media_mounts entries are left untouched, since they hold the operator's existing music library, not data Navidrome itself generates.
• Deletes the {{ cs_navidrome_user }} user, its home directory, and the {{ cs_navidrome_group }} group.

Tags

• navidrome: Deploy Navidrome.
• navidrome_install: Install Navidrome.
• navidrome_restic_backup: Run Restic backup for Navidrome.
• navidrome_restic_restore: Restore Navidrome's data from the latest Restic snapshot.
• dangerously_cleanup_navidrome: Destructive. Removes the Navidrome Docker container, closes its UFW port, and deletes cs_navidrome_container_root. Never included by the plain navidrome 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 navidrome