Alojar Verdaccio en un VPS: registro npm/yarn/pnpm privado

Tres situaciones hacen indispensable un registro npm privado. La primera es gestionar librerías JavaScript internas: si desarrollas un design system, utilidades de negocio o clientes de API específicos de tu organización, publicarlos en npmjs.org los expone a todo internet. Un registro privado los mantiene detrás de tu infraestructura, versionados y accesibles solo a tus desarrolladores y pipelines.

La segunda es la resiliencia de CI: npmjs.org experimenta cortes varias veces al año, y cada uno puede bloquear tus despliegues durante horas. Verdaccio cachea cada paquete descargado: el segundo npm install — en CI o en local — nunca vuelve a tocar la red. Tus builds se aceleran y se independizan de la disponibilidad del registro público.

La tercera es el trabajo offline o en entornos sin acceso a internet. Una vez calentada la caché, Verdaccio sirve todos los paquetes vistos previamente sin conexión — útil para entornos de cumplimiento estricto, pipelines on-premise o demos sin Wi-Fi. Todo en un único contenedor Docker ligero (menos de 128 MB RAM), sin base de datos externa y sin configuración compleja.

Verdaccio es uno de los servicios más ligeros que puedes desplegar en un VPS. La lista de requisitos es intencionalmente corta: un VPS con 1 vCPU, 512 MB de RAM (Verdaccio usa menos de 128 MB en funcionamiento normal) y Docker instalado. No se necesita dominio para empezar — accedes al registro mediante un túnel SSH desde tu workstation o desde un runner CI.

Para acceso permanente del equipo o CI externos, adjunta un dominio desde tu panel de ServOrbit: nginx lo proxificará sobre HTTPS automáticamente, y el certificado TLS es gestionado por ServOrbit sin ninguna acción de tu parte. Para almacenamiento, planifica espacio en disco proporcional a tu uso: los paquetes públicos cacheados y tus paquetes privados se acumulan en un volumen Docker persistente — unos pocos gigabytes son suficientes para la mayoría de proyectos con un equipo de 5 a 10 desarrolladores.

Por defecto, Verdaccio aplica una única regla: cada paquete se busca primero en local y luego se proxifica a npmjs.org si está ausente. Esta regla funciona para empezar, pero la mayoría de equipos quieren refinar el comportamiento por namespace.

La configuración vive en config.yaml, accesible desde el volumen Docker (verdaccio-storage). La sección packages: define reglas por patrón de nombre. Para un namespace privado (@acme/*), puedes desactivar el proxy a npmjs.org y permitir solo usuarios autenticados:

packages:
  '@acme/*':
    access: $authenticated
    publish: $authenticated
  '**':
    access: $all
    proxy: npmjs

Después de la modificación, reinicia el contenedor: docker compose restart verdaccio. Esta configuración garantiza que tus paquetes privados nunca lleguen a npmjs.org.

Para GitHub Actions, define NPM_CONFIG_REGISTRY y el token de autenticación ${{ secrets.VERDACCIO_TOKEN }} en las variables de entorno del workflow:

jobs:
  build:
    env:
      NPM_CONFIG_REGISTRY: https://verdaccio.tu-dominio.com
      NPM_CONFIG_//verdaccio.tu-dominio.com/:_authToken: ${{ secrets.VERDACCIO_TOKEN }}

Obtén el token con npm token create --registry https://verdaccio.tu-dominio.com desde cualquier cuenta de usuario Verdaccio. Almacena el token en los secretos de CI, no en archivos del repositorio. Para GitLab CI, la sintaxis equivalente va en la sección variables: de tu .gitlab-ci.yml.

El cacheo de paquetes reduce el tiempo de instalación de node_modules de 30–60 segundos a 2–5 segundos en builds repetidas, ya que los paquetes públicos se sirven desde la caché de Verdaccio en lugar de descargarse de npmjs.org. Para maximizar el beneficio en CI, ejecuta una etapa de pre-calentamiento antes de los builds de ramas de funcionalidades.

Verdaccio usa por defecto autenticación htpasswd con hash bcrypt. Para los equipos que necesitan integración con sistemas de identidad existentes, Verdaccio soporta plugins de autenticación de terceros: LDAP, GitLab, GitHub OAuth, Keycloak y otros.

Para tokens CI, usa npm token create --registry https://verdaccio.tu-dominio.com en lugar de contraseñas en texto plano. Almacénalos como secretos de CI (${{ secrets.VERDACCIO_TOKEN }} en GitHub Actions). Los tokens se pueden revocar individualmente sin afectar a otros usuarios.

En ServOrbit, Verdaccio está vinculado a 127.0.0.1 y expuesto solo a través del proxy inverso nginx — el puerto 4873 nunca es directamente accesible desde internet. Para máxima seguridad, habilita la autenticación obligatoria de lectura (access: $authenticated en config.yaml) si tu registro contiene paquetes sensibles o propietarios.