Cómo autoalojar Verdaccio en 2026: autenticación de npm, almacenamiento y TLS

Autoalojar Verdaccio resulta interesante con el primer redeploy, no con el primer docker run. Si los clientes de npm envían las credenciales a otro host o el almacenamiento de paquetes es de solo lectura, Docker puede seguir informando de que el proceso está perfectamente saludable. El despliegue siguiente se organiza en torno a un comportamiento observable: iniciar sesión con npm, publicar un paquete con scope, instalarlo desde un proyecto limpio y confirmar que se ha almacenado en caché un paquete upstream.

El propósito de Verdaccio es claro: un registro privado de npm para paquetes internos. Esta descripción indica qué debe permanecer público, qué debe seguir siendo privado y qué debe poder reconstruir una copia de seguridad.

Puertos, procesos y servicios privados

Un diagrama útil de Verdaccio muestra la ruta pública, el puerto privado 4873, el límite de estado y todos los requisitos de soporte. Indica qué flechas transportan credenciales y cuáles representan tráfico de usuario normal. El contrato de red de Verdaccio incluye configuración persistente, almacenamiento htpasswd y almacenamiento de objetos opcional. Mantén los endpoints privados en DNS interno, permite únicamente las llamadas salientes necesarias y asigna a Verdaccio una credencial de servicio con permisos limitados.

Demuestra el diagrama con una acción real: inicia sesión con npm, publica un paquete con scope, instálalo desde un proyecto limpio y confirma que se ha almacenado en caché un paquete upstream. La presión más probable provendrá del almacenamiento de tarballs, las operaciones de metadatos, las instalaciones simultáneas y la latencia hasta los registros upstream configurados; monitoriza esa ruta en lugar de tratar todas las solicitudes HTTP como equivalentes.

Convierte el comando local en un servicio inspeccionable

Usa un comando que deje expuestas todas las decisiones importantes. Esta configuración base enlaza Verdaccio con el loopback del host, añade los volúmenes de datos conocidos y proporciona el primer ajuste necesario. Añade los parámetros de conexión revisados para la configuración persistente, el almacenamiento htpasswd y el almacenamiento de objetos opcional; utiliza nombres privados para los servicios 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

Sustituye las etiquetas flotantes por una versión o un digest probados. Después del inicio, inspecciona docker logs --tail 200 verdaccio y confirma que el proceso escucha en el puerto 4873. A continuación, ejecuta la acción de aceptación de Verdaccio; una respuesta de la página raíz no demuestra que el escenario completo funcione: inicia sesión con npm, publica un paquete con scope, instálalo desde un proyecto limpio y confirma que se ha almacenado en caché un paquete upstream.

TLS es sencillo; las URL generadas no

Configura la URL pública y la URL del registro de npm con el mismo origen HTTPS. Envía el hostname elegido al puerto 4873 del contenedor, reenvía el host original y el esquema HTTPS, y evita publicar un segundo origen directo.

Prueba Verdaccio desde un cliente externo limpio. Separa un fallo de ingress del límite conocido de la aplicación: los clientes de npm envían las credenciales a otro host o el almacenamiento de paquetes es de solo lectura. Un error de certificado, DNS o 502 pertenece al enrutamiento; una solicitud que llega a Verdaccio y falla después pertenece al estado de la aplicación, la capacidad o uno de sus requisitos de soporte. La guía de TLS con dominio personalizado cubre el primer grupo.

Restaura Verdaccio en un host vacío

En Verdaccio, la seguridad del redeploy empieza por los tarballs de paquetes, los metadatos, la configuración y los archivos de autenticación. Monta /verdaccio/storage antes del bootstrap, escribe datos de muestra inocuos y sustituye el contenedor para demostrar que esa ruta es realmente persistente. Prueba la ruta sustituyendo el contenedor mientras existan los datos de muestra inocuos; esto revela los volúmenes apuntados un directorio demasiado arriba o demasiado abajo.

A continuación, prueba la recuperación ante desastres en un host vacío. Utiliza cuando sea necesario una exportación de base de datos coherente con la aplicación y verifica que se recuperan los tarballs privados, los metadatos, los usuarios y la configuración, y que el proyecto limpio instala el paquete con la misma integridad. La guía de copias de seguridad de bases de datos probadas mediante restauración ofrece un objetivo más sólido que limitarse a comprobar que se ha creado un archivo de archivo.

Credenciales, roles y superficies expuestas

En Verdaccio, la superficie valiosa no tiene por qué ser la página de inicio. El error principal consiste en permitir publicaciones anónimas o utilizar una configuración de uplink con permisos de escritura. Contrarréstalo de forma deliberada: deniega las publicaciones anónimas, limita los maintainers mediante scopes y mantén la autenticación de npm asociada al host exacto del registro HTTPS.

VERDACCIO_PUBLIC_URL es configuración, no un secreto; mantén su valor explícito y protege por separado las credenciales que utiliza Verdaccio. Usa un usuario sin privilegios para el contenedor cuando la imagen lo admita y no montes credenciales que no estén relacionadas. Aplica límites de velocidad o tamaño en el ingress, donde el trabajo no confiable puede consumir almacenamiento de tarballs, operaciones de metadatos, instalaciones simultáneas y latencia hasta los registros upstream configurados.

Pruebas de fallos para Verdaccio

Las pruebas de capacidad deben ejercitar el almacenamiento de tarballs, las operaciones de metadatos, las instalaciones simultáneas y la latencia hasta los registros upstream configurados, no repetir una solicitud a /. Ejecuta el escenario «iniciar sesión con npm, publicar un paquete con scope, instalarlo desde un proyecto limpio y confirmar que se ha almacenado en caché un paquete upstream» con una concurrencia realista y registra la latencia, la tasa de errores y el crecimiento del almacenamiento.

La planificación de upgrades debe tener en cuenta este riesgo: la sintaxis de configuración, los plugins de autenticación y los metadatos de paquetes deben probarse con la versión major de Verdaccio de destino. Prueba la nueva release con datos representativos, repite después la transacción de aceptación y compara el resultado. Si los clientes de npm envían las credenciales a otro host o el almacenamiento de paquetes es de solo lectura, captura la transacción fallida e inspecciona el primer límite implicado en lugar de asumir que el ingress es responsable.

Demuestra el despliegue de Verdaccio de extremo a extremo

No conviertas el tráfico del primer usuario en la prueba de aceptación de Verdaccio. Prepara un estado de muestra inocuo y ejecuta la acción completa «iniciar sesión con npm, publicar un paquete con scope, instalarlo desde un proyecto limpio y confirmar que se ha almacenado en caché un paquete upstream». Anota la URL pública exacta, el resultado, la referencia de la imagen y el intervalo de logs asociados a la ejecución.

Sustituye el contenedor y repite la prueba sin reconstruir los datos. Después, recupera el servicio en un host vacío; la condición de recuperación es que se restauren los tarballs privados, los metadatos, los usuarios y la configuración, y que el proyecto limpio instale el paquete con la misma integridad. Observa el almacenamiento de tarballs, las operaciones de metadatos, las instalaciones simultáneas y la latencia hasta los registros upstream configurados en cada ejecución, y define una alerta en torno a la degradación de la transacción, no en torno a las métricas de un contenedor inactivo.

Una última comprobación debe fallar deliberadamente: deniega temporalmente a la identidad de prueba el acceso a la configuración persistente, el almacenamiento htpasswd y el almacenamiento de objetos opcional. Verifica que el mensaje resultante de Verdaccio identifique el límite relevante en lugar de provocar el borrado de datos o un reinicio infinito. Restaura la condición válida y confirma que la misma transacción de muestra funciona. Mantén esta prueba breve en la checklist de release.

Mantén Verdaccio explícito mientras Dockup gestiona el enrutamiento

Para Verdaccio, Dockup puede crear la ruta y el certificado TLS, conservar los volúmenes, entregar secretos y situar la configuración persistente, el almacenamiento htpasswd y el almacenamiento de objetos opcional en una red privada mientras despliega en Dockup o en servidores conectados.

El release gate sigue siendo la transacción concreta de Verdaccio: iniciar sesión con npm, publicar un paquete con scope, instalarlo desde un proyecto limpio y confirmar que se ha almacenado en caché un paquete upstream. Verifica también la condición de restauración: se recuperan los tarballs privados, los metadatos, los usuarios y la configuración, y el proyecto limpio instala el paquete con la misma integridad. Estas dos comprobaciones muestran si el despliegue funciona y si puede recuperarse.

Preguntas frecuentes

¿Qué necesita Verdaccio para un despliegue en producción?

Enruta el contenedor de Verdaccio en el puerto 4873 mediante un único origen HTTPS. El requisito de red de soporte incluye configuración persistente, almacenamiento htpasswd y almacenamiento de objetos opcional. No consideres que Verdaccio está listo hasta que puedas iniciar sesión con npm, publicar un paquete con scope, instalarlo desde un proyecto limpio y confirmar que se ha almacenado en caché un paquete upstream.

¿Qué datos de Verdaccio deben incluirse en una copia de seguridad?

Haz persistente /verdaccio/storage e incluye los tarballs de paquetes, los metadatos, la configuración y los archivos de autenticación en el mismo manifiesto de recuperación. Una restauración limpia de Verdaccio solo es válida cuando se recuperan los tarballs privados, los metadatos, los usuarios y la configuración, y el proyecto limpio instala el paquete con la misma integridad.

¿Verdaccio necesita HTTPS detrás de un reverse proxy?

Usa HTTPS para el origen público de Verdaccio y mantén el puerto 4873 en la ruta interna. Aplica correctamente el ajuste de Verdaccio: configura la URL pública y la URL del registro de npm con el mismo origen HTTPS. En Verdaccio, HTTPS protege las credenciales o el contenido de usuario durante el tránsito y mantiene coherente el comportamiento del cliente, que depende del origen.

¿Cómo debe probarse un upgrade de Verdaccio?

Restaura el estado actual de Verdaccio en un despliegue aislado, aplica la versión candidata y repite su transacción de aceptación. Presta especial atención, porque la sintaxis de configuración, los plugins de autenticación y los metadatos de paquetes deben probarse con la versión major de Verdaccio de destino. Conserva la imagen anterior de Verdaccio hasta comprender los límites de migración de datos y rollback.