Cómo instalar Node.js y PM2 en Ubuntu: una guía completa de producción

Node.js es un entorno de ejecución de JavaScript asíncrono y orientado a eventos, construido sobre el motor V8 de Chrome, diseñado para ejecutar código JavaScript del lado del servidor con alto rendimiento. PM2 es un gestor de procesos de nivel de producción para aplicaciones Node.js que proporciona daemonización, recuperación automática ante fallos, agregación de registros, balanceo de carga en modo clúster y generación de scripts de inicio — todo desde una única interfaz CLI.

Esta guía cubre todos los métodos de instalación, opciones de configuración y patrones operativos que necesitas para ejecutar aplicaciones Node.js de forma fiable en Ubuntu 20.04, 22.04 o 24.04 LTS en un entorno de producción.

Requisitos previos

Antes de continuar, confirma lo siguiente:

• Sistema operativo: Ubuntu 20.04, 22.04 o 24.04 LTS (servidor o escritorio)
• Privilegios de usuario: `sudo` o acceso root
• Acceso a la red: HTTPS de salida para descargar paquetes y scripts
• curl instalado: Ejecuta `sudo apt install curl -y` si aún no está presente

Si estás ejecutando esto en un servidor en la nube, un entorno de VPS Hosting es el destino de despliegue más común para cargas de trabajo Node.js, y todo lo que se indica en esta guía se aplica directamente.

Paso 1: Actualizar los paquetes del sistema

Sincroniza siempre tu índice de paquetes y aplica las actualizaciones pendientes antes de instalar nuevo software. Los metadatos de paquetes desactualizados son una fuente frecuente de conflictos de dependencias.

“`bash

sudo apt update

sudo apt upgrade -y

“`

Una vez completada la actualización, reinicia si se actualizó el kernel:

“`bash

sudo reboot

“`

Paso 2: Instalar Node.js — Elegir el método correcto

Existen tres métodos principales de instalación de Node.js en Ubuntu. Cada uno tiene ventajas e inconvenientes distintos en términos de control de versiones, aislamiento y disponibilidad a nivel de sistema.

Comparación de métodos

Método 1: Instalar Node.js mediante NodeSource (recomendado para servidores)

NodeSource mantiene repositorios Debian/Ubuntu actualizados para cada línea de versión activa de Node.js. Este es el enfoque preferido para servidores de producción donde se requiere una versión única y estable a nivel de sistema.

Añadir el repositorio NodeSource para la versión LTS actual:

“`bash

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash –

“`

Este script realiza varias acciones: detecta tu versión de Ubuntu, añade el repositorio apt de NodeSource correspondiente, importa la clave de firma GPG y ejecuta `apt-get update`. El indicador `-E` preserva tus variables de entorno al escalar a sudo, lo cual es importante si tienes configurados ajustes de proxy.

Instalar Node.js y npm:

“`bash

sudo apt install nodejs -y

“`

El paquete NodeSource incluye tanto `node` como `npm` en un único paquete `nodejs`. A diferencia del paquete universe de Ubuntu, no los separa.

Verificar la instalación:

“`bash

node -v

npm -v

“`

Ejemplo de salida esperada:

“`

v20.14.0

10.7.0

“`

Fijar una versión principal específica: Si necesitas Node.js 18 en lugar del LTS actual, reemplaza `setup_lts.x` por `setup_18.x` en el comando curl. Las versiones disponibles incluyen `setup_18.x`, `setup_20.x` y `setup_22.x`.

Método 2: Instalar Node.js mediante NVM (recomendado para desarrollo y entornos multiversión)

NVM (Node Version Manager) instala Node.js en tu directorio de inicio, sin requerir privilegios root ni para Node.js en sí ni para los paquetes npm instalados globalmente. Esto elimina los problemas de permisos que suelen surgir al ejecutar `npm install -g` en Node.js instalado a nivel de sistema.

Instalar NVM:

“`bash

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

“`

Consulta el repositorio oficial de NVM para obtener la etiqueta de la última versión antes de ejecutar este comando — el número de versión en la URL cambia con cada lanzamiento.

Recargar el entorno de shell:

“`bash

source ~/.bashrc

“`

Si usas Zsh, carga `~/.zshrc` en su lugar. El instalador de NVM añade su bloque de inicialización al archivo de configuración de shell que detecte.

Instalar la última versión LTS de Node.js:

“`bash

nvm install –lts

“`

Instalar una versión específica junto al LTS:

“`bash

nvm install 18

nvm install 20

“`

Cambiar entre versiones instaladas:

“`bash

nvm use 20

nvm alias default 20

“`

El comando `alias default` establece la versión que se activa en nuevas sesiones de shell, lo cual es fundamental para scripts y trabajos cron que no cargan tu perfil de shell interactivo.

Verificar:

“`bash

node -v

npm -v

“`

Problema crítico de NVM en producción: Dado que NVM tiene alcance de usuario, los scripts de inicio de PM2 y las unidades systemd no tendrán acceso al binario Node.js gestionado por NVM a menos que configures explícitamente la ruta. Consulta el Paso 5 para saber cómo gestionar esto correctamente.

Paso 3: Instalar PM2

PM2 se distribuye como un paquete npm y debe instalarse globalmente para que su CLI esté disponible en todo el sistema.

Instalar PM2:

“`bash

sudo npm install -g pm2

“`

Si instalaste Node.js mediante NVM, omite `sudo`:

“`bash

npm install -g pm2

“`

Verificar la instalación:

“`bash

pm2 -v

“`

Instalar una versión específica de PM2 (útil al fijar la infraestructura):

“`bash

sudo npm install -g pm2@5.3.1

“`

PM2 versión 5.x es la línea estable actual. Introdujo mejoras significativas en el panel web (pm2 plus), la rotación de registros y el sistema de módulos en comparación con la v4.

Paso 4: Gestionar aplicaciones Node.js con PM2

Iniciar una aplicación

Navega al directorio de tu aplicación e iníciala:

“`bash

cd /var/www/my-app

pm2 start app.js –name "my-app"

“`

Asigna siempre un indicador `–name`. Sin él, PM2 usa el nombre del archivo como nombre del proceso, lo que resulta ambiguo cuando tienes múltiples servicios.

Iniciar con opciones adicionales:

“`bash

pm2 start app.js –name "my-app" –watch –max-memory-restart 300M

“`

• `–watch`: Reinicia el proceso cuando cambian los archivos fuente (útil en staging, no recomendado en producción)
• `–max-memory-restart 300M`: Reinicia automáticamente el proceso si supera 300 MB de memoria RSS — una salvaguarda crítica contra las fugas de memoria

Ver los procesos en ejecución

“`bash

pm2 list

“`

Muestra una tabla con el ID de proceso, nombre, modo (fork/clúster), PID, estado, uso de CPU, consumo de memoria y número de reinicios.

Para un panel en tiempo real:

“`bash

pm2 monit

“`

Controlar procesos

“`bash

pm2 restart my-app # Graceful restart

pm2 reload my-app # Zero-downtime reload (cluster mode only)

pm2 stop my-app # Stop without removing from process list

pm2 delete my-app # Stop and remove from process list

“`

La diferencia entre `restart` y `reload`: `restart` mata el proceso e inicia uno nuevo, causando una breve interrupción. `reload` (disponible solo en modo clúster) cicla los workers de uno en uno, manteniendo la disponibilidad durante todo el proceso. Usa siempre `reload` en despliegues de clúster en producción.

Gestión de registros

“`bash

pm2 logs # Stream logs from all processes

pm2 logs my-app # Stream logs for a specific process

pm2 logs my-app –lines 200 # Show last 200 lines

pm2 flush # Clear all log files

“`

PM2 almacena los registros en `~/.pm2/logs/` de forma predeterminada. Para servidores de producción, instala el módulo de rotación de registros para evitar el agotamiento del disco:

“`bash

pm2 install pm2-logrotate

pm2 set pm2-logrotate:max_size 50M

pm2 set pm2-logrotate:retain 10

pm2 set pm2-logrotate:compress true

“`

Esto rota los registros cuando alcanzan 50 MB, conserva 10 archivos comprimidos y evita el crecimiento descontrolado de los registros — un problema común en servidores de larga ejecución que frecuentemente se pasa por alto hasta que el espacio en disco se agota.

Paso 5: Configurar PM2 para que se inicie con el sistema

PM2 debe configurarse para sobrevivir a los reinicios del servidor. Esto se gestiona mediante una unidad de servicio systemd generada por el propio PM2.

Generar el comando de inicio:

“`bash

pm2 startup

“`

PM2 mostrará un comando adaptado a tu sistema init y usuario actual. Tiene este aspecto:

“`

[PM2] Init System found: systemd

[PM2] To setup the Startup Script, copy/paste the following command:

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

“`

Copia y ejecuta ese comando exacto. No lo modifiques — la ruta al binario de PM2 y el directorio de inicio deben coincidir con la configuración de tu sistema.

Configuración de inicio específica para NVM: Si instalaste Node.js mediante NVM, la ruta en el comando generado apuntará a tu binario gestionado por NVM. Esto es correcto, pero debes asegurarte de que la versión NVM esté establecida como predeterminada antes de ejecutar `pm2 startup`:

“`bash

nvm alias default 20

pm2 startup

“`

Guardar la lista de procesos actual:

“`bash

pm2 save

“`

Esto escribe la lista de procesos en `~/.pm2/dump.pm2`. Al reiniciar, la unidad systemd lee este archivo y restaura todos los procesos guardados. Si añades o eliminas aplicaciones más adelante, ejecuta `pm2 save` de nuevo para actualizar la instantánea.

Verificar que la unidad systemd está activa:

“`bash

systemctl status pm2-ubuntu

“`

Reemplaza `ubuntu` con tu nombre de usuario real.

Paso 6: Despliegue en producción con archivos de ecosistema de PM2

Para cualquier cosa más allá de una aplicación de script único, usa el archivo de configuración de ecosistema de PM2. Proporciona definiciones de procesos reproducibles y controladas por versiones, y elimina la necesidad de recordar indicadores CLI largos.

Generar el archivo de ecosistema

“`bash

pm2 ecosystem

“`

Esto crea `ecosystem.config.js` en el directorio actual.

Una configuración de ecosistema lista para producción

“`javascript

module.exports = {

apps: [

{

name: 'api-server',

script: './src/server.js',

instances: 'max',

exec_mode: 'cluster',

watch: false,

max_memory_restart: '500M',

log_date_format: 'YYYY-MM-DD HH:mm:ss Z',

error_file: '/var/log/pm2/api-server-error.log',

out_file: '/var/log/pm2/api-server-out.log',

merge_logs: true,

env: {

NODE_ENV: 'development',

PORT: 3000

},

env_production: {

NODE_ENV: 'production',

PORT: 8080

}

},

{

name: 'worker',

script: './src/worker.js',

instances: 2,

exec_mode: 'fork',

cron_restart: '0 2 * * *',

env_production: {

NODE_ENV: 'production'

}

}

]

};

“`

Decisiones clave de configuración explicadas:

• `instances: 'max'`: PM2 genera automáticamente un worker por núcleo lógico de CPU. En un servidor de 4 núcleos, esto crea 4 procesos Node.js, aprovechando completamente el hardware.
• `exec_mode: 'cluster'`: Utiliza el módulo de clúster integrado de Node.js. Todas las instancias comparten el mismo puerto a través del balanceo de carga de sockets del sistema operativo.
• `exec_mode: 'fork'`: Ejecuta el proceso como un proceso hijo independiente. Requerido para aplicaciones que no son servidores HTTP (workers de cola, trabajos programados, servidores WebSocket con sesiones sticky).
• `merge_logs: true`: Combina la salida estándar de todas las instancias del clúster en un único archivo de registro, lo que facilita significativamente el análisis de registros.
• `cron_restart`: Programa reinicios automáticos usando sintaxis cron. Útil para workers que acumulan estado o para aplicar cambios de configuración nocturnos.

Iniciar con el archivo de ecosistema

“`bash

pm2 start ecosystem.config.js –env production

pm2 save

“`

Flujo de trabajo de despliegue sin tiempo de inactividad

Al desplegar una nueva versión de tu aplicación:

“`bash

git pull origin main

npm install –production

pm2 reload ecosystem.config.js –env production

“`

`pm2 reload` envía una señal `SIGINT` a cada worker de uno en uno, espera a que el nuevo worker esté listo y luego termina el anterior. Tu aplicación debe gestionar `SIGINT` de forma elegante y señalar la disponibilidad usando `process.send('ready')` para que esto funcione correctamente.

Manejador de apagado elegante en tu aplicación:

“`javascript

process.on('SIGINT', () => {

server.close(() => {

console.log('HTTP server closed');

process.exit(0);

});

});

“`

Paso 7: Monitorización y observabilidad de PM2

Monitorización integrada

“`bash

pm2 monit

“`

Muestra gráficos de CPU y memoria en tiempo real para cada proceso en el terminal.

Información de procesos

“`bash

pm2 show my-app

“`

Muestra metadatos detallados: tiempo de actividad, número de reinicios, versiones, ruta del intérprete, variables de entorno y ubicaciones de archivos de registro.

Panel web de PM2 (PM2 Plus)

PM2 ofrece un panel de monitorización alojado en pm2.io. Conecta tu servidor:

“`bash

pm2 link <secret_key> <public_key>

“`

Esto proporciona métricas históricas, alertas y gestión remota de procesos — especialmente valioso cuando se gestionan múltiples servidores o cuando se necesita visibilidad sin acceso SSH.

Paso 8: Actualizar Node.js y PM2

Actualizar PM2

“`bash

sudo npm install -g pm2@latest

pm2 update

“`

`pm2 update` es esencial después de actualizar el binario de PM2 — actualiza el daemon PM2 en memoria sin interrumpir los procesos en ejecución.

Actualizar Node.js mediante NodeSource

Vuelve a ejecutar el script de configuración para la nueva versión principal:

“`bash

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash –

sudo apt install nodejs -y

“`

Después de actualizar Node.js, reinicia PM2 para asegurarte de que utiliza el nuevo binario:

“`bash

pm2 restart all

“`

Actualizar Node.js mediante NVM

“`bash

nvm install 22

nvm alias default 22

nvm use 22

pm2 restart all

“`

Si cambiaste la versión predeterminada de NVM, regenera el script de inicio de PM2 para actualizar la ruta del binario en la unidad systemd:

“`bash

pm2 unstartup

pm2 startup

pm2 save

“`

Consideraciones de seguridad

Ejecutar aplicaciones Node.js en producción requiere atención más allá de la gestión de procesos:

• Ejecutar como usuario no root: Nunca ejecutes PM2 o Node.js como root. Crea un usuario de sistema dedicado (`adduser –system –group nodeapp`) y ejecuta PM2 bajo esa cuenta.
• Gestión de variables de entorno: No codifiques secretos en `ecosystem.config.js`. Usa un archivo `.env` cargado mediante `dotenv`, o inyecta secretos a través de tu pipeline de despliegue. El archivo de ecosistema normalmente se confirma en el control de versiones.
• Proxy inverso: Coloca Nginx o Caddy delante de tu aplicación Node.js. Esto gestiona la terminación TLS, el servicio de archivos estáticos, la limitación de velocidad y el almacenamiento en búfer de solicitudes. Combina esto con una solución de SSL Certificates para aplicar HTTPS.
• Reglas de firewall: Bloquea el acceso directo al puerto de tu Node.js (p. ej., 3000, 8080) desde internet público. Solo el proxy inverso debe comunicarse con Node.js.
• Límites de recursos: Establece `max_memory_restart` en PM2 y configura los valores `ulimit` a nivel de sistema para evitar que un proceso desbocado desestabilice el servidor.

Para despliegues de producción de alto tráfico donde el aislamiento de recursos es crítico, un entorno de Dedicated Servers proporciona control total del hardware y elimina el problema del vecino ruidoso inherente a la infraestructura compartida.

Elegir el entorno de alojamiento adecuado para Node.js

Lista de verificación de decisiones técnicas

Usa esta lista de verificación antes de desplegar Node.js y PM2 en producción:

• [ ] Node.js instalado mediante NodeSource (servidor) o NVM (desarrollo) — no el paquete universe de Ubuntu
• [ ] PM2 instalado globalmente con los permisos correctos para tu método de instalación
• [ ] Aplicación iniciada con el indicador `–name` y un umbral `–max-memory-restart` definido
• [ ] Modo clúster habilitado para servidores HTTP; modo fork usado para workers en segundo plano
• [ ] `pm2 startup` ejecutado y el comando generado ejecutado con sudo
• [ ] `pm2 save` ejecutado después de configurar todos los procesos
• [ ] Módulo de rotación de registros instalado y configurado
• [ ] Nginx o Caddy configurado como proxy inverso con TLS
• [ ] La aplicación gestiona `SIGINT` de forma elegante para recargas sin tiempo de inactividad
• [ ] Secretos gestionados fuera de `ecosystem.config.js`
• [ ] Unidad systemd de PM2 verificada con `systemctl status pm2-<username>`
• [ ] El firewall bloquea el acceso directo a los puertos de Node.js desde internet público

Preguntas frecuentes

¿Cuál es la diferencia entre el modo fork y el modo clúster de PM2?

El modo fork genera la aplicación como un único proceso hijo — una instancia, un núcleo de CPU utilizado. El modo clúster usa el módulo de clúster nativo de Node.js para generar múltiples procesos worker que comparten el mismo puerto TCP, lo que permite una utilización real de múltiples núcleos y recargas sin tiempo de inactividad. Usa el modo clúster para servidores HTTP/HTTPS y el modo fork para workers, trabajos cron o aplicaciones que mantienen estado interno incompatible con el uso compartido multiproceso.

¿Por qué PM2 no se reinicia después de un reinicio del servidor aunque haya ejecutado `pm2 startup`?

La causa más común es que `pm2 save` no se ejecutó después de configurar los procesos, por lo que el archivo dump está vacío o no existe. La segunda causa más común es una discrepancia de ruta de NVM: si la versión predeterminada de NVM se cambió después de generar el script de inicio, la unidad systemd apunta a un binario inexistente. Resuelve esto ejecutando `pm2 unstartup`, estableciendo el valor predeterminado correcto de NVM y luego volviendo a ejecutar `pm2 startup` y `pm2 save`.

¿Puede PM2 gestionar procesos que no sean de Node.js?

Sí. PM2 puede gestionar cualquier ejecutable especificando el intérprete. Por ejemplo: `pm2 start script.py –interpreter python3`. Esto hace que PM2 sea útil como supervisor de procesos de propósito general para arquitecturas de microservicios de lenguajes mixtos.

¿Cómo ejecuto múltiples aplicaciones Node.js en diferentes puertos detrás de un único servidor?

Define cada aplicación como una entrada separada en `ecosystem.config.js` con variables de entorno `PORT` distintas. Configura Nginx como proxy inverso con bloques `server` separados o directivas `location` que enruten a cada puerto. Todas las aplicaciones comparten el mismo daemon PM2 y se gestionan a través de una única vista `pm2 list`.

¿Debo usar NVM o NodeSource para un VPS de producción?

NodeSource es generalmente preferible para servidores de producción. Instala Node.js como un paquete del sistema, haciéndolo disponible para todos los usuarios y servicios del sistema sin dependencias de inicialización de shell. El modelo de activación por usuario y por shell de NVM introduce modos de fallo sutiles en unidades systemd, trabajos cron y pipelines CI/CD que se ejecutan fuera de una sesión de shell interactiva. Reserva NVM para máquinas de desarrollo local donde gestionar múltiples versiones de Node.js simultáneamente es un requisito real.