NPM privado: instalar y configurar Verdaccio

Cuando nos planteamos tener nuestro NPM privado tenemos varias opciones que van desde la contratación de uno de los servicios NPM disponibles en la nube hasta la instalación de nuestro propio servidor. Para este segundo caso podemos utilizar un paquete gratuito como Verdaccio, una potente solución, fácil de utilizar y bastante flexible.

Verdaccio es el heredero y continuador de Sinopia, que fue descontinuado hace algún tipo. Aunque podemos encontrar bastantes referencias a Sinopia, su falta de actualización desde hace algunos años ha hecho que Verdaccio recoja este desarrollo como un fork y lo mantenga actualizado y en funcionamiento. Sinopia es soportado al 100% en Verdaccio, aunque este último lo ha evolucionado y ampliado, pero manteniendo la compatibilidad hacia atrás.

¿Qué es Verdaccio?

Es una aplicación desarrollada en Node.js que ofrece un servicio compatible con NPM, YARM y PNPM, así como una interfaz web que permite gestionar un registro privado de paquetes. En él podremos definir paquetes privados que puedan ser utilizados y compartidos en nuestros proyectos con igual rapidez y sencillez que los paquetes públicos.

También es un proxy del servicio NPM, de tal forma que cualquier llamada para cargar un paquete NPM público pase por el servidor Verdaccio, funcionado como una caché de las llamadas al repositorio público. Esto es especialmente útil si por algún motivo nuestra infraestructura no dispone de acceso directo a Internet por alguna circunstancia.

Aprovechando esta característica de proxy, permite sobre escribir un paquete público, por ejemplo, si una dependencia tiene un error o vulnerabilidad y no hemos conseguido que el autor la corrija, podemos publicar un paquete con el mismo nombre y versión dentro de nuestro NPM privado, sobre escribiendo el paquete conflictivo.

Es una aplicación extensible que se puede completar por medio de plugins, por ejemplo, para establecer un mecanismo de identificación de usuarios personalizado. Dispone de un API que se puede utilizar desde Node.

Uso básico

Es bastante sencillo de utilizar y configurar, pudiendo hacer uso de su imagen Docker o instalarlo con bastante rapidez, aunque deberemos tener en cuenta algunas cosas para poderlo configurar en un entorno de producción con todas las garantías.

Para hacer una primera prueba de concepto simplemente tenemos que instalar Verdaccio en una maquina donde previamente hayamos instalado Node.

npm install -g verdaccio

Ahora sólo tenemos que arrancar el servidor:

verdaccio

Este programa creará un pequeño repositorio por defecto y arrancará un servidor en http://localhost:4873/. Aunque luego veremos cómo configurar esto, de momento nos sirve para empezar a probar.

Desde este momento podemos hacer uso del servicio NPM privado que nos ofrece Verdaccio. Por ejemplo, si queremos obtener un paquete público por medio del proxy deberemos utilizar:

npm install lodash --registry http://localhost:4873/

Al incorporar --registry http://localhost:4873/ le estamos diciendo a NPM que, en vez de ir directamente a los servidores públicos, haga la llamada a nuestro servidor. Si vamos a la consola donde tenemos abierto Verdaccio veremos algo de este tipo:

 http --> 200, req: 'GET https://registry.npmjs.org/lodash' (streaming)
 http --> 200, req: 'GET https://registry.npmjs.org/lodash', bytes: 0/182744
 http <-- 200, user: undefined(127.0.0.1), req: 'GET /lodash', bytes: 0/13451
 http <-- 200, user: undefined(127.0.0.1), req: 'GET /lodash/-/lodash-4.17.10.tgz', bytes: 0/305668

Si queremos publicar nuestro paquete privado, antes tendremos que crear un nuevo usuario. Para ello podemos utilizar la siguiente instrucción que nos preguntará el nombre del usuario, la password y un correo:

npm adduser --registry http://localhost:4873

A partir de aquí, podemos utilizar esta orden para publicar nuestros paquetes privados:

npm publish --registry http://localhost:4873/

Si no queremos estar incluyendo --registry http://localhost:4873/ en todas las instrucciones sólo tenemos que definir el registry por defecto con:

npm set registry http://localhost:4873/

Ahora, si queremos publicar una nueva versión de nuestro paquete se utilizará nuestro servidor Verdaccio y sólo tenemos que hacer:

npm version patch
npm publish

Si tenemos curiosidad de saber dónde nos está guardando toda esta información, podemos buscar en la consola de Verdaccio donde está el fichero de configuración. Es el primer mensaje que saca por consola y mostrará algo de este tipo:

warn --- config file  - /home/user/.config/verdaccio/config.yaml

Si abres el fichero podrás ver con facilidad dónde se están guardando los paquetes, por ejemplo:

storage: /home/user/.local/share/verdaccio/storage

Y en que fichero se están guardando los usuarios que se vayan registrando:

auth:
  htpasswd:
    file: ./htpasswd

Instalación en un entorno de producción

Aunque para hacer unas pruebas es suficiente, en un entorno de uso real no tiene mucho sentido que mantengamos una consola con Verdaccio arrancado en http://localhost:4873/. Por ello vamos a explicar paso a paso como podemos instalar y configurar Verdaccio en un entorno de producción. Es posible que la configuración precisa que debas utilizar en tu entorno varíe en algunos aspectos de lo que aquí recogemos, pero esta guía te servirá como referencia.

Dependencias

En primer lugar, vamos a instalar una serie de software de base que necesitamos tener disponibles si partimos de una máquina recién instalada:

sudo apt-get update
sudo apt-get install build-essential curl

Instalamos Node:

cd ~
curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash -
sudo apt-get install -y nodejs

Instalamos Nginx y comprobamos que está funcionando:

sudo apt-get install nginx
sudo service nginx status

Instalamos pm2:

sudo npm install pm2 -g

Instalamos de Verdaccio:

sudo npm install verdaccio -g

Usuario para la ejecución del servicio

Es recomendable crear un usuario sin permisos para hacer sudo y que ejecute Verdaccio. Hemos decidido utilizar el nombre verduser, pero puedes elegir el nombre que quieras.

sudo adduser --disabled-login --gecos 'Verdaccio User' verduser

Con este usuario, ejecutamos una vez Verdaccio para que cree la configuración por defecto:

sudo su verduser
cd ~
verdaccio

Mostrará un mensaje de este tipo:

 warn --- config file  - /home/ verduser/verdaccio/config.yaml
 warn --- http address - http://localhost:4873/ - verdaccio/2.7.4

Ahora podemos cerrar el programa con un simple Ctrl+C y pasar a configurar todo para que funcione correctamente.

Configuración

Lo primero que vamos a hacer es editar el fichero config.yaml para evitar que se registren nuevos usuarios por medio de npm adduser. Para ello vamos a incluir max_users: -1. Quedará más o menos de esta forma:

auth:
  htpasswd:
    file: ./htpasswd
    # Maximum amount of users allowed to register, defaults to "+inf".
    # You can set this to -1 to disable registration.
    #max_users: 1000
    max_users: -1

Si queremos que el acceso sea restringido, es decir, que personas no identificadas no puedan descargar paquetes de nuestro servidor, entonces debemos editar el fichero config.yaml modificando las entradas access: $all por access: $authenticated. Nota: aparece dos veces y, en principio, deberíamos cambiar las dos, aunque también podemos restringir el acceso sólo para paquetes que cumplan cierto esquema en su nombre.

Una vez que tengamos esta configuración activa, es conveniente que añadamos --auth-all cuando usemos npm adduser --registry http://localhost:4873/ --auth-all y de esta forma indicamos que se utilizará la identificación para todas las operaciones.

Ahora que está todo configurado, vamos a arrancar Verdaccio con pm2 y hacer que se mantenga en ejecución, aunque reiniciemos el equipo:

sudo su verduser
cd ~
pm2 start `which verdaccio`
pm2 save
pm2 startup

Esta última instrucción nos dirá que ejecutemos una orden de este tipo:

sudo env PATH=$PATH:/usr/bin /usr/lib/node_modules/pm2/bin/pm2 \
startup systemd \
-u verduser \
--hp /home/verduser

Nota: recuerda que nuestro usuario verduser no puede hacer sudo, por lo que tendremos que salir de su entorno y ejecutar la orden que nos han indicado.

Podemos comprobar que todo ha funcionado ejecutando:

curl http://localhost:4873/ 

Obtendremos el HTML de la página de inicio de la web de Verdaccio.

Usuarios

Como hemos deshabilitado la creación de usuarios por medio de npm adduser, debemos crear nuevos usuarios por otros medios. Para ello debemos instalar el paquete apache2-utils:

sudo apt-get install apache2-utils

Con el usuario verduser nos movemos a la carpeta donde tiene que estar el fichero htpasswd y ejecutamos la creación del nuevo usuario:

sudo su verduser
cd ~/verdaccio
htpasswd ./htpasswd newuser

Nos pedirá la password dos veces y a partir de ese momento, el nuevo usuario creado podrá identificarse por medio de npm adduser.

npm adduser --registry http://myserver --always-auth

Nota: puede resultar confuso que npm adduser sirva para dar de alta y para identificarse, pero funciona así.

Configurar NGINX

El último paso es configurar NGINX. Lo cierto es que podemos utilizar Verdaccio sin esta configuración, pero resulta bastante recomendable utilizar un proxy inverso como NGINX para gestionar el acceso público a nuestros servicios http.

La forma más rápida de realizar esta configuración es editar el fichero /etc/nginx/sites-available/default incluyendo esta configuración:

location / {
    # First attempt to serve request as file, then
    # as directory, then fall back to displaying a 404.
    #try_files $uri $uri/ =404;
    proxy_pass http://127.0.0.1:4873/;
    proxy_set_header Host $host;
}

Podemos comprobar que la configuración es correcta con:

sudo nginx -t

Una vez comprobado, recargamos NGINX con:

sudo service nginx restart

Aunque no lo incluimos aquí, seguramente se deberá dar un nombre que se pueda resolver por DNS a esta máquina y configurar un certificado SSL para que la conexión sea siempre por HTTPS, por ejemplo, con certbot.

Una vez asignado el nombre, y para evitar algunos confusos problemas, debemos incluir el nombre seleccionado en el fichero config.yaml, donde quedaría más o menos de esta forma:

url_prefix: https://npm.myserver.com/

Hay más opciones de configuración e instalación de Verdaccio que puedes consultar en su documentación.

Conclusiones

Aunque puede parecer un poco extenso, lo cierto es que es muy sencillo instalar y configurar Verdaccio y con poco esfuerzo aprovechar todas las posibilidades que nos ofrece disponer de un servicio NPM privado.

Si te quieres saltar todo este proceso de instalación, puedes obtener una suscripción a la versión privada del propio NPM o contratar un servicio NPM alternativo como Gemfury. Tienes tantas opciones, que no hay excusa para no disponer de un registro privado de paquetes para tu organización.