Navidrome Docker Compose: Servidor Musical Self-Hosted 2026

Con Navidrome Docker Compose puedes montar en minutos un servidor de música compatible con la API Subsonic/OpenSubsonic, con interfaz web moderna y consumo de recursos muy bajo. Es una alternativa excelente si ya self-hosteas multimedia y quieres separar la música de un stack más pesado como Jellyfin, manteniendo tus archivos locales bajo tu control.

• Qué lograrás: docker compose up, volúmenes para datos y biblioteca, variables útiles y buenas prácticas de permisos.
• Qué opcional verás: integración con Caddy Docker Compose, Traefik Docker Compose o Nginx Proxy Manager Docker Compose para HTTPS.
• Prerrequisitos: Docker Engine y plugin Compose instalados; carpeta de música accesible en el host.

El objetivo de esta guía es que copies el YAML, lo adaptes a tus rutas y tengas Navidrome Docker Compose estable en menos de una tarde, con criterios claros de seguridad y mantenimiento. Si vienes de otros tutoriales del blog, reconocerás el mismo estilo de volúmenes explícitos y reinicios bajo política unless-stopped.

¿Por qué usar Navidrome Docker Compose en tu homelab?

Esta pila con Navidrome y Compose destaca por tres motivos que suelen pesar en entornos reales: ligereza, compatibilidad con clientes móviles y escritorio vía API Subsonic, y una comunidad activa detrás del proyecto open source. A diferencia de soluciones orientadas solo a vídeo, Navidrome está pensado para colecciones de audio grandes, con metadatos, listas inteligentes y transcoding configurable por usuario.

Si ya tienes experiencia con la categoría Docker Compose del blog, el patrón será familiar: un servicio, dos volúmenes (datos + música), un puerto publicado y variables de entorno documentadas en la referencia oficial de opciones. Para comparar con otro servidor multimedia del catálogo, revisa Jellyfin Docker Compose: Navidrome no sustituye a Jellyfin en vídeo, pero complementa muy bien cuando quieres música con menos CPU y RAM.

La imagen oficial publicada en Docker Hub (deluan/navidrome) soporta amd64 y varias arquitecturas ARM, lo que facilita desplegar Navidrome desde un mini PC hasta una Raspberry Pi con almacenamiento USB.

Navidrome Docker Compose: requisitos previos

Antes de crear el archivo Compose, confirma que tu host cumple lo básico: Docker instalado y el comando docker compose version operativo (la sintaxis moderna unifica el plugin; la guía de orquestación está en documentación Docker Compose). Necesitas una ruta en el disco donde guardar la base de datos y caché de Navidrome (directorio /data dentro del contenedor) y otra con tus archivos de música, montada en solo lectura si no quieres que el contenedor modifique los ficheros.

Los permisos importan: la documentación recomienda ejecutar el contenedor con el mismo UID:GID que posee la música en el host para evitar errores de lectura. En el ejemplo usaremos user: "1000:1000"; sustituye por el resultado de id en tu servidor. Si mezclas NFS o CIFS, valida que el usuario del contenedor vea los mismos IDs efectivos. Un error habitual al documentar internamente Navidrome Docker Compose es olvidar anotar el UID usado; meses después nadie entiende por qué el contenedor “dejó de ver” la música tras un cambio de ownership en el NAS.

En términos de red, el puerto por defecto del servicio es 4533. Solo expón ese puerto a Internet si entiendes el riesgo; lo habitual es mantener el servicio detrás de un proxy con TLS y reglas de acceso. Las buenas prácticas generales de endurecimiento del demonio están resumidas en seguridad de Docker Engine.

Navidrome Docker Compose: archivo YAML recomendado

Crea un directorio de proyecto, por ejemplo ~/navidrome, y dentro un docker-compose.yml. El siguiente manifiesto sigue la guía oficial de instalación con Docker y añade volúmenes nombrados, red aislada y límites razonables para entornos domésticos.

services:
  navidrome:
    image: deluan/navidrome:latest
    container_name: navidrome
    user: "1000:1000"
    ports:
      - "4533:4533"
    restart: unless-stopped
    environment:
      ND_SCANSCHEDULE: "@every 1m"
      ND_LOGLEVEL: info
      ND_SESSIONTIMEOUT: 24h
    volumes:
      - navidrome_data:/data
      - ./music:/music:ro
    networks:
      - media_net
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M

volumes:
  navidrome_data:

networks:
  media_net:
    driver: bridge

Sustituye ./music por la ruta absoluta de tu biblioteca en el host. El volumen navidrome_data persistirá la base de datos SQLite, miniaturas y configuración generada. Si prefieres rutas bind directas en lugar de volumen nombrado para datos, puedes mapear algo como - /srv/navidrome/data:/data siguiendo el mismo criterio de propietario. Versionar el fichero compose en Git (sin secretos) ayuda a que el equipo repita el mismo Navidrome Docker Compose en entornos de prueba y producción.

Arranca el stack con docker compose up -d y revisa logs con docker compose logs -f navidrome. La primera ejecución puede tardar unos minutos si la colección es grande, porque el escaneo inicial indexa etiquetas y carátulas. Este flujo es el núcleo práctico de cualquier despliegue reproducible en CI o en documentación interna de tu homelab.

Navidrome Docker Compose: variables ND_ esenciales

Más allá del YAML, Navidrome se gobierna con prefijo ND_. Algunas claves que suelen ajustarse en producción son:

• ND_BASEURL: URL pública si sirves detrás de subruta o dominio; necesaria para enlaces correctos y algunos clientes.
• ND_SCANSCHEDULE / ND_SCANINTERVAL: controlan con qué frecuencia se reescanea la biblioteca; evita valores agresivos en discos lentos.
• ND_SESSIONTIMEOUT: caducidad de sesión web; subirla mejora comodidad en casa, bajarla endurece equipos compartidos.
• ND_ENABLETRANSCODINGCONFIG y opciones de bitrate: útiles si reproducirás en móviles con ancho de banda limitado.

La lista completa y comportamientos por defecto están en la documentación enlazada arriba; no dupliques variables que no necesites: menos superficie de configuración equivale a menos sorpresas al actualizar la imagen. Cuando versiones nuevas aparezcan en el repositorio GitHub de Navidrome, revisa el changelog antes de fijar etiquetas :latest en entornos críticos.

Un consejo de operación: si usas Navidrome con varias bibliotecas en Docker, consulta la guía de multi-biblioteca en el sitio del proyecto para montar volúmenes adicionales y asignar permisos por usuario dentro de la aplicación.

Navidrome Docker Compose: primer acceso y escaneo

Tras el arranque, abre http://IP_DEL_SERVIDOR:4533 y crea el usuario administrador que te pedirá la interfaz. Desde ahí puedes forzar un escaneo manual o esperar al schedule definido en ND_SCANSCHEDULE. Si no ves álbumes, casi siempre el fallo es de permisos o de ruta de volumen mal enlazada; verifica que dentro del contenedor exista /music con ficheros legibles para el UID configurado. Una vez validado el flujo, puedes considerar tu Navidrome Docker Compose listo para pasar a hardening de red y copias de seguridad programadas.

La experiencia web permite crear usuarios no administradores, playlists y favoritos independientes por cuenta. Para móviles y reproductores externos, Navidrome expone la API compatible Subsonic; el catálogo de aplicaciones recomendadas está en Navidrome Apps. Elegir un cliente bueno marca la diferencia en Android Auto, iOS o escritorio.

Si integras Navidrome con servicios de scrobbling (Last.fm, ListenBrainz), hazlo tras estabilizar la URL pública y los certificados, porque algunos callbacks esperan HTTPS válido. Este detalle suele ahorrar horas de troubleshooting en redes domésticas con DNS dinámico.

Navidrome Docker Compose detrás de proxy HTTPS

En producción casera “seria”, no publiques el puerto 4533 directamente. Coloca Navidrome en la misma red Docker que tu proxy inverso y termina TLS allí. Los artículos enlazados al inicio cubren tres patrones frecuentes en el blog; elige el que ya mantengas para no fragmentar certificados.

Configura ND_BASEURL con el esquema y host correctos, por ejemplo https://music.tudominio.com. Si el proxy añade cabeceras X-Forwarded-*, revisa en la documentación si necesitas ajustes adicionales de confianza de proxies; un error típico es generar URLs http mezcladas tras el TLS offload.

Para equipos que ya despliegan Navidrome junto a otros contenedores, unificar el docker-compose en un solo archivo con perfiles (profiles:) puede aislar el servicio de música de stacks de desarrollo que reinician a menudo. La referencia del formato Compose ayuda cuando empiezas a condicionar servicios: Compose file reference.

Navidrome Docker Compose: diagnóstico y fallos típicos

Cuando el contenedor arranca pero la interfaz muestra biblioteca vacía, el orden de comprobación debería ser: (1) docker compose exec navidrome ls -la /music para confirmar montaje y permisos; (2) revisar que el UID del proceso coincida con el propietario de los ficheros en el host; (3) subir temporalmente ND_LOGLEVEL a debug y observar si el escaneo reporta errores de lectura o etiquetas corruptas. En volúmenes de red, los bloqueos intermitentes suelen manifestarse como escaneos que nunca terminan: en ese caso fija un ND_SCANSCHEDULE menos agresivo y valida latencia hacia el NAS.

Si los clientes móviles no autentican pero el navegador sí, revisa URL base, certificados intermedios y que el reloj del dispositivo sea correcto. Otro síntoma frecuente tras mover Navidrome Docker Compose a otro servidor es olvidar actualizar ND_BASEURL: los enlaces generados en correos o playlists compartidas seguirán apuntando al dominio antiguo hasta corregir la variable y reiniciar.

Los límites de recursos del ejemplo YAML (deploy.resources.limits) son ignorados por Docker Compose clásico en modo no-Swarm; si necesitas topes reales en un solo host, valora mem_limit en el servicio o cgroups externos. Documentar estas decisiones evita que un compañero copie el archivo en un entorno distinto y espere comportamientos que Compose no aplica.

Navidrome Docker Compose: transcoding y uso de CPU

El transcoding al vuelo convierte formatos en tiempo de reproducción para ahorrar ancho de banda o compatibilizar reproductores antiguos. En Docker, el contenedor necesita acceso a binarios de ffmpeg según la imagen oficial; la configuración fina (bitrates, códecs) se expone en la UI por usuario o jugador. Si notas picos de CPU al primer play de un tema, suele ser normal; si se mantienen, revisa que no estés forzando resampling innecesario en clientes que ya soportan el códec nativo.

Para homelabs con CPU modesta, desactiva transcoding global donde no haga falta y deja que los clientes locales lean FLAC u otros formatos sin conversión. En el otro extremo, servidores con muchos núcleos pueden permitir políticas más agresivas para usuarios remotos. Ajustar estos parámetros después de desplegar Navidrome Docker Compose en producción es más seguro que adivinar valores antes de conocer el perfil real de escucha de tu hogar u oficina.

Si planeas contenedores adicionales en el mismo host (por ejemplo un worker de conversión de medios), separa servicios en redes Docker distintas para que un pico de carga no compita por el mismo pool de CPU asignado en systemd o en el hipervisor.

Navidrome Docker Compose: copias de seguridad y actualización

Mantener un procedimiento escrito para Navidrome Docker Compose —qué volúmenes copiar, en qué orden parar servicios y cómo validar el restore— reduce el estrés cuando cambias de disco o migras de VPS. Incluye en ese runbook la versión exacta de la imagen y el fichero compose usado, porque restaurar datos sin la misma versión puede forzar migraciones imprevistas.

Tu dato crítico no es solo la música (que ya deberías respaldar en origen), sino el volumen /data con la base y metadatos generados. Para backup consistente, detén el contenedor o usa snapshots del volumen si tu almacenamiento lo permite, y copia el directorio de datos. Restaurar es tan simple como volver a montar el volumen antes de levantar de nuevo el stack.

Actualizar imagen: docker compose pull && docker compose up -d. Lee notas de versión por si hay migraciones de esquema. Si usas pin de versión (deluan/navidrome:0.xx.x), actualiza la etiqueta explícitamente tras probar en un entorno de prueba.

Monitoriza uso de disco: las carátulas y cachés crecen con la biblioteca. Una política de retención de logs (ND_LOGLEVEL) equilibrada evita verbosidad eterna en discos pequeños. Con estos hábitos, el stack se mantiene estable meses sin intervención.

FAQ sobre Navidrome Docker Compose

¿Puedo usar SQLite embebido en Docker?
Sí; Navidrome usa SQLite en /data por defecto, adecuado para hogar y pequeñas oficinas.

¿Sustituye a Plex o Jellyfin para música?
Sí en el ámbito audio; no cubre bibliotecas de vídeo como Jellyfin. Pueden convivir en el mismo host con puertos y volúmenes separados.

¿Cómo evito ejecutar como root?
Mantén la directiva user alineada con el propietario de los ficheros, como en el ejemplo.

¿Qué pasa si cambio la ruta de música?
Actualiza el bind mount y vuelve a escanear; considera una ventana de mantenimiento para reindexar.

¿Es razonable exponerlo a Internet?
Solo con TLS, contraseñas fuertes y, si es posible, VPN o SSO; trátalo como cualquier servicio doméstico expuesto.

En conjunto, un despliegue Navidrome Docker Compose ofrece un camino corto hacia música self-hosted profesional, alineado con las prácticas que ya usas en otros tutoriales del blog. Ajusta variables, protege el acceso y mantén copias del volumen de datos para dormir tranquilo mientras disfrutas tu biblioteca en cualquier cliente compatible.