Como fazer o self-hosting do Verdaccio em 2026: autenticação npm, armazenamento e TLS

Fazer o self-hosting do Verdaccio torna-se interessante no primeiro redeploy, não no primeiro docker run. Se os clientes npm enviarem as credenciais para outro host ou o armazenamento de pacotes estiver somente leitura, o Docker ainda poderá informar que o processo está perfeitamente saudável. O deployment abaixo é organizado em torno de comportamentos observáveis: fazer login com npm, publicar um pacote com escopo, instalá-lo a partir de um projeto limpo e confirmar que um pacote upstream foi armazenado em cache.

O objetivo do Verdaccio é explícito: um registry npm privado para pacotes internos. Essa descrição indica o que deve permanecer público, o que deve continuar privado e o que um backup precisa reconstruir.

Portas, processos e serviços privados

Um diagrama útil do Verdaccio mostra a rota pública, a porta privada 4873, o limite de estado e todos os requisitos de suporte. Marque quais setas transportam credenciais e quais representam tráfego comum de utilizadores. O contrato de rede do Verdaccio inclui configuração persistente, armazenamento htpasswd e armazenamento de objetos opcional. Mantenha os endpoints privados em DNS interno, permita apenas as chamadas de saída necessárias e forneça ao Verdaccio uma credencial de serviço com escopo definido.

Comprove o diagrama com uma ação real: faça login com npm, publique um pacote com escopo, instale-o a partir de um projeto limpo e confirme que um pacote upstream foi armazenado em cache. A pressão mais provável vem do armazenamento de tarballs, das operações de metadados, das instalações concorrentes e da latência até os registries upstream configurados; monitore esse caminho em vez de tratar todas as requisições HTTP como equivalentes.

Transforme o comando local em um serviço inspecionável

Use um comando que exponha todas as escolhas importantes. Esta configuração base vincula o Verdaccio ao loopback do host, adiciona os mounts de dados conhecidos e fornece a primeira configuração necessária. Adicione as configurações de conexão revisadas para a configuração persistente, o armazenamento htpasswd e o armazenamento de objetos opcional; use nomes privados para serviços privados.

docker run -d \
  --name verdaccio \
  --restart unless-stopped \
  -p 127.0.0.1:4873:4873 \
  -v verdaccio-data:/verdaccio/storage \
  -e VERDACCIO_PUBLIC_URL=https://app.example.com \
  verdaccio/verdaccio:latest

Substitua tags flutuantes por uma versão ou digest testado. Depois da inicialização, inspecione docker logs --tail 200 verdaccio e confirme que o processo está escutando na porta 4873. Em seguida, execute a ação de aceitação do Verdaccio; uma resposta da página inicial não pode provar que o cenário completo funciona: faça login com npm, publique um pacote com escopo, instale-o a partir de um projeto limpo e confirme que um pacote upstream foi armazenado em cache.

TLS é fácil; as URLs geradas, não

Defina a URL pública e a URL do registry npm para a mesma origem HTTPS. Encaminhe o hostname escolhido para a porta 4873 do container, repasse o host original e o esquema HTTPS e evite publicar uma segunda origem direta.

Teste o Verdaccio a partir de um cliente externo limpo. Separe uma falha de ingress do limite conhecido da aplicação — os clientes npm enviam as credenciais para outro host ou o armazenamento de pacotes está somente leitura. Um erro de certificado, DNS ou 502 pertence ao roteamento; uma requisição que chega ao Verdaccio e falha posteriormente pertence ao estado da aplicação, à capacidade ou a um requisito de suporte. O guia de TLS para domínios personalizados aborda o primeiro grupo.

Restaure o Verdaccio em um host vazio

Para o Verdaccio, a segurança do redeploy começa com tarballs de pacotes, metadados, configuração e arquivos de autenticação. Monte /verdaccio/storage antes do bootstrap, grave dados de exemplo inofensivos e substitua o container para provar que esse caminho é realmente persistente. Teste o caminho substituindo o container enquanto os dados de exemplo inofensivos ainda existirem; isso revela mounts apontados para um diretório acima ou abaixo do correto.

Em seguida, teste a recuperação de desastre em um host vazio. Use uma exportação consistente com a aplicação quando necessário e verifique se os tarballs privados, metadados, utilizadores e configurações retornam e se o projeto limpo instala o mesmo package integrity. O guia de backup de bases de dados com restauração testada oferece um objetivo mais sólido do que simplesmente verificar se um arquivo de archive foi criado.

Credenciais, funções e superfícies expostas

No Verdaccio, a superfície valiosa não é necessariamente a página inicial. O principal erro é permitir publicação anônima ou usar uma configuração de uplink com permissão de escrita. Enfrente-o deliberadamente: negue a publicação anônima, defina escopos para maintainers e mantenha a autenticação npm vinculada ao host exato do registry HTTPS.

VERDACCIO_PUBLIC_URL é configuração, não um segredo; mantenha seu valor explícito e proteja as credenciais separadas usadas pelo Verdaccio. Use um utilizador não privilegiado no container quando a imagem oferecer suporte e não monte credenciais não relacionadas. Aplique limites de taxa ou tamanho no ingress, onde trabalho não confiável pode consumir armazenamento de tarballs, operações de metadados, instalações concorrentes e latência até os registries upstream configurados.

Simulações de falhas do Verdaccio

Os testes de capacidade devem exercitar o armazenamento de tarballs, as operações de metadados, as instalações concorrentes e a latência até os registries upstream configurados, não uma requisição repetida a /. Execute o cenário “fazer login com npm, publicar um pacote com escopo, instalá-lo a partir de um projeto limpo e confirmar que um pacote upstream foi armazenado em cache” com concorrência realista e registre a latência, a taxa de erros e o crescimento do armazenamento.

O planejamento de upgrades deve considerar este risco: a sintaxe de configuração, os plugins de autenticação e os metadados de pacotes devem ser testados em relação à versão major de destino do Verdaccio. Teste a nova release com dados representativos, depois repita a transação de aceitação e compare o resultado. Se os clientes npm enviarem as credenciais para outro host ou o armazenamento de pacotes estiver somente leitura, capture a transação que falhou e inspecione o primeiro limite envolvido, em vez de presumir que o ingress é responsável.

Comprove o deployment do Verdaccio de ponta a ponta

Não transforme o tráfego do primeiro utilizador no teste de aceitação do Verdaccio. Prepare um estado de exemplo inofensivo e execute a ação completa: “fazer login com npm, publicar um pacote com escopo, instalá-lo a partir de um projeto limpo e confirmar que um pacote upstream foi armazenado em cache”. Registre a URL pública exata, o resultado, a referência da imagem e o intervalo de logs associado à execução.

Substitua o container e repita sem reconstruir os dados. Em seguida, faça a recuperação em um host vazio; a condição de recuperação é que os tarballs privados, metadados, utilizadores e configurações retornem e que o projeto limpo instale o mesmo package integrity. Observe o armazenamento de tarballs, as operações de metadados, as instalações concorrentes e a latência até os registries upstream configurados em cada execução e defina um alerta em torno da degradação da transação, não das métricas de um container ocioso.

Uma verificação final deve falhar de propósito: negue temporariamente à identidade de teste o acesso à configuração persistente, ao armazenamento htpasswd e ao armazenamento de objetos opcional. Verifique se a mensagem resultante do Verdaccio identifica o limite relevante, em vez de acionar a exclusão de dados ou um restart interminável. Restaure a condição válida e confirme que a mesma transação de exemplo funciona. Mantenha esta simulação curta no checklist de release.

Mantenha o Verdaccio explícito enquanto o Dockup cuida do roteamento

Para o Verdaccio, o Dockup pode criar a rota e o certificado TLS, preservar mounts, fornecer secrets e colocar a configuração persistente, o armazenamento htpasswd e o armazenamento de objetos opcional em uma rede privada durante o deployment no Dockup ou em servidores conectados.

O gate de release continua sendo a transação concreta do Verdaccio: fazer login com npm, publicar um pacote com escopo, instalá-lo a partir de um projeto limpo e confirmar que um pacote upstream foi armazenado em cache. Verifique também a condição de restauração — os tarballs privados, metadados, utilizadores e configurações retornam e o projeto limpo instala o mesmo package integrity. Essas duas verificações mostram se o deployment funciona e se pode ser recuperado.

Perguntas frequentes

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

Encaminhe o container do Verdaccio na porta 4873 por meio de uma única origem HTTPS. O requisito de rede de suporte é composto por configuração persistente, armazenamento htpasswd e armazenamento de objetos opcional. Não considere o Verdaccio pronto até conseguir fazer login com npm, publicar um pacote com escopo, instalá-lo a partir de um projeto limpo e confirmar que um pacote upstream foi armazenado em cache.

Quais dados do Verdaccio devem fazer parte de um backup?

Mantenha /verdaccio/storage persistente e inclua tarballs de pacotes, metadados, configuração e arquivos de autenticação no mesmo manifesto de recuperação. Uma restauração limpa do Verdaccio só é bem-sucedida quando os tarballs privados, metadados, utilizadores e configurações retornam e o projeto limpo instala o mesmo package integrity.

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

Use HTTPS para a origem pública do Verdaccio e mantenha a porta 4873 na rota interna. Aplique corretamente a configuração do Verdaccio: defina a URL pública e a URL do registry npm para a mesma origem HTTPS. Para o Verdaccio, o HTTPS protege as credenciais ou o conteúdo do utilizador durante o transporte e mantém consistente o comportamento do cliente sensível à origem.

Como testar um upgrade do Verdaccio?

Restaure o estado atual do Verdaccio em um deployment isolado, aplique a versão candidata e repita sua transação de aceitação. Preste atenção especial, pois a sintaxe de configuração, os plugins de autenticação e os metadados de pacotes devem ser testados em relação à versão major de destino do Verdaccio. Mantenha a imagem anterior do Verdaccio até compreender os limites de migração de dados e de rollback.