Como fazer self-host do Navidrome em 2026: mounts de música, scans e apps Subsonic

Se você já tentou fazer self-host do Navidrome, provavelmente conhece bem este estado frustrante: a UI aparece, mas os scans não encontram arquivos porque o caminho de música do host foi montado incorretamente. Recriar o container raramente resolve um desacordo entre URLs, estado e dependências.

Este passo a passo usa um critério concreto de conclusão — fazer o scan de uma biblioteca de música read-only, verificar metadados e artwork, reproduzir uma faixa por meio de um cliente Subsonic e salvar uma playlist. Cada escolha de configuração é avaliada com base nesse critério, e não apenas em um badge verde do container.

Faça backup do estado que o Navidrome não consegue recriar

Defina o recovery point e o recovery time do Navidrome em termos do banco de dados do Navidrome, do cache de artwork, das playlists e da biblioteca de música original. Monte /data antes do bootstrap, grave dados de exemplo inofensivos e substitua o container para provar que esse caminho é realmente persistente. Um named volume resolve a persistência entre redeploys; ele não resolve um comprometimento nem a perda do servidor.

Prepare um ambiente de restore limpo, use a mesma versão fixada da aplicação e prove que usuários, playlists, histórico de reprodução e metadados retornam, e que o mesmo cliente Subsonic reproduz uma faixa conhecida. Registre os comandos, os ajustes de ownership e o tempo decorrido. O guia de backup é um padrão útil: um backup só é confiável depois do restore, não depois do upload.

Inicie o Navidrome sem ocultar as partes móveis

Use o container como um runtime substituível, não como a fonte da verdade.

docker run -d \
  --name navidrome \
  --restart unless-stopped \
  -p 127.0.0.1:4533:4533 \
  -v navidrome-data:/data \
  -v /srv/music:/music:ro \
  -e ND_BASEURL=/ \
  deluan/navidrome:latest

Confirme o requisito local antes de expor o serviço: um mount read-only da biblioteca de música e dados de aplicação com permissão de escrita. Inspecione o usuário do container, os caminhos com permissão de escrita e o listener associado antes de expô-lo. Execute a ação completa — fazer o scan de uma biblioteca de música read-only, verificar metadados e artwork, reproduzir uma faixa por meio de um cliente Subsonic e salvar uma playlist — e salve a referência exata da image que produziu o resultado.

Escolha a menor topologia viável para o Navidrome

Comece pelo network namespace do Navidrome: o web listener dele é a porta 4533, não uma porta do host copiada de um tutorial para laptop. O requisito do runtime local é um mount read-only da biblioteca de música e dados de aplicação com permissão de escrita. Registre isso ao lado da image e da porta para que um host substituto receba a mesma capacidade local.

Depois que o requisito for atendido, execute o cenário completo — fazer o scan de uma biblioteca de música read-only, verificar metadados e artwork, reproduzir uma faixa por meio de um cliente Subsonic e salvar uma playlist. Registre logs e métricas do tempo de scan da biblioteca, CPU de transcoding, cache de artwork, streams concorrentes e throughput de disco. Essas evidências formam a primeira arquitetura conhecida como funcional e tornam testáveis as migrações posteriores entre o compute da Dockup e um servidor conectado.

TLS é fácil; URLs geradas não são

Defina ND_BASEURL ao servir a partir de um subpath; caso contrário, prefira um host HTTPS dedicado. Envie o hostname escolhido para a porta 4533 do container, encaminhe o host original e o esquema HTTPS e evite publicar uma segunda origem direta.

Teste o Navidrome a partir de um cliente externo limpo. Separe uma falha de ingress do limite conhecido da aplicação — os scans não encontram arquivos porque o caminho de música do host foi montado incorretamente. Um erro de certificado, DNS ou 502 pertence ao routing; uma requisição que chega ao Navidrome e falha depois pertence ao estado da aplicação, à capacidade ou ao requisito de suporte. O guia de TLS para custom domain aborda o primeiro grupo.

Cinco verificações mais fortes do que o health do container

Antes da chegada de usuários reais, crie uma release worksheet para o Navidrome. Ela deve indicar a image fixada, a porta 4533, a origem canônica, os caminhos persistentes e o responsável por um mount read-only da biblioteca de música e pelos dados de aplicação com permissão de escrita. Anexe o resultado esperado desta transação: fazer o scan de uma biblioteca de música read-only, verificar metadados e artwork, reproduzir uma faixa por meio de um cliente Subsonic e salvar uma playlist.

Use a worksheet depois de uma substituição normal e de um restore limpo. O recovery só é aceito quando usuários, playlists, histórico de reprodução e metadados retornam, e o mesmo cliente Subsonic reproduz uma faixa conhecida. Colete também um resource trace curto cobrindo o tempo de scan da biblioteca, CPU de transcoding, cache de artwork, streams concorrentes e throughput de disco; mantenha-o junto da release para que futuras mudanças de capacidade sejam comparadas com a mesma workload.

Inclua uma falha controlada: envie uma entrada inofensiva próxima ao limite de recurso ou formato associado a este boundary: os scans não encontram arquivos porque o caminho de música do host foi montado incorretamente. Confirme que o Navidrome reporta o problema no boundary correto, restaure a condição válida e execute novamente a transação. Isso verifica a visibilidade dos erros, não apenas o sucesso, e impede que uma interface com aparência saudável oculte um worker, callback ou conexão de banco de dados quebrado.

Logs que respondem à próxima pergunta

Use fazer o scan de uma biblioteca de música read-only, verificar metadados e artwork, reproduzir uma faixa por meio de um cliente Subsonic e salvar uma playlist como smoke test do Navidrome após cada deployment. As métricas de suporte são o tempo de scan da biblioteca, CPU de transcoding, cache de artwork, streams concorrentes e throughput de disco; crie alertas quando esses recursos se aproximarem de um ponto que degrade a ação do usuário.

O principal risco de mudança é que as migrações do banco de dados do Navidrome e o comportamento do scanner devem ser testados enquanto os arquivos de música originais permanecem intactos. Uma release segura começa com um snapshot que possa ser restaurado e valida qualquer mudança de estado irreversível antes de mover o tráfego. Quando os scans não encontrarem arquivos porque o caminho de música do host foi montado incorretamente, mantenha o container com falha tempo suficiente para ler sua configuração e o primeiro erro.

Não dê ao Navidrome acesso ao host inteiro

Feche a janela de bootstrap assim que existir o primeiro administrador confiável. A armadilha concreta do Navidrome é montar a biblioteca de música com permissão de escrita sem um motivo; o boundary mais seguro é montar a música como read-only, proteger as contas e expor apenas o serviço de streaming, não a biblioteca do host.

ND_BASEURL é configuração, não um secret; mantenha seu valor explícito enquanto protege as credenciais separadas usadas pelo Navidrome. A rede privada deve transportar as credenciais das dependências, e as roles dentro do Navidrome devem conceder a menor ação útil. Mantenha bodies sensíveis de requests e respostas de providers fora dos logs de rotina.

Mantenha o Navidrome explícito enquanto a Dockup cuida do routing

Routing, certificados, substituição de serviços e storage conectado são alvos razoáveis de automação. A Dockup cuida disso para o Navidrome e pode provisionar o banco de dados gerenciado relacionado ou conectar-se a serviços no servidor do próprio cliente.

O que ela não deve inventar é a trust policy do Navidrome. Depois do deployment, defina ND_BASEURL ao servir a partir de um subpath; caso contrário, prefira um host HTTPS dedicado, aplique este boundary — monte a música como read-only, proteja as contas e exponha apenas o serviço de streaming, não a biblioteca do host — e verifique o resultado deste cenário: fazer o scan de uma biblioteca de música read-only, verificar metadados e artwork, reproduzir uma faixa por meio de um cliente Subsonic e salvar uma playlist. O resultado é uma infraestrutura de um clique com um acceptance test específico da aplicação.

Perguntas frequentes

O que o Navidrome precisa para um deployment em produção?

Faça o routing do container do Navidrome na porta 4533 por meio de uma única origem HTTPS. O requisito do runtime local é um mount read-only da biblioteca de música e dados de aplicação com permissão de escrita. Não considere o Navidrome pronto até conseguir fazer o scan de uma biblioteca de música read-only, verificar metadados e artwork, reproduzir uma faixa por meio de um cliente Subsonic e salvar uma playlist.

Quais dados do Navidrome devem entrar no backup?

Persista /data e inclua o banco de dados do Navidrome, o cache de artwork, as playlists e a biblioteca de música original no mesmo recovery manifest. Um restore limpo do Navidrome só é aprovado quando usuários, playlists, histórico de reprodução e metadados retornam, e o mesmo cliente Subsonic reproduz uma faixa conhecida.

O Navidrome precisa de HTTPS atrás de um reverse proxy?

Use HTTPS para a origem pública do Navidrome e mantenha a porta 4533 na rota interna. Aplique corretamente a configuração do Navidrome: defina ND_BASEURL ao servir a partir de um subpath; caso contrário, prefira um host HTTPS dedicado. Para o Navidrome, o HTTPS protege credenciais ou conteúdo de usuários em trânsito e mantém consistente o comportamento do cliente sensível à origem.

Como testar um upgrade do Navidrome?

Restaure o estado atual do Navidrome em um deployment isolado, aplique a versão candidata e repita sua acceptance transaction. Dê atenção especial ao fato de que as migrações do banco de dados do Navidrome e o comportamento do scanner devem ser testados enquanto os arquivos de música originais permanecem intactos. Mantenha a image anterior do Navidrome até que os limites de data-migration e rollback sejam compreendidos.