Skip to main content

Instalación de Node.js LTS 22 y npm en Ubuntu con CloudLinux CageFS

Contexto

Guía para instalar Node.js 22 LTS en Ubuntu cuando el servidor utiliza CloudLinux con CageFS. La documentación oficial de CloudLinux está orientada a RPM, pero este proceso está validado para sistemas Debian/Ubuntu.

Prerequisitos

  • Ubuntu (validado en versiones 20.04+)
  • CloudLinux con CageFS activo
  • Acceso root
  • Usuario con configuración mysql/mariadb ya tuneada (socket o .my.cnf)

Parte 1: Instalación base de Node.js

1. Verificar estado actual (opcional)

# Ver si ya tienes Node instalado
node --version
npm --version

# Ver repositorios de Node configurados
grep -r "nodesource" /etc/apt/sources.list.d/

2. Limpiar instalaciones previas (si existen)

# Eliminar repositorios antiguos de NodeSource
sudo rm -f /etc/apt/sources.list.d/nodesource.list
sudo rm -f /etc/apt/keyrings/nodesource.gpg

# Eliminar versiones antiguas
sudo apt remove nodejs npm -y
sudo apt autoremove -y

3. Instalar Node.js 22 LTS desde NodeSource

# Descargar e instalar el script de setup oficial
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

# Instalar Node.js (incluye npm automáticamente)
sudo apt install -y nodejs

# Verificar instalación en sistema base
node --version    # Debería mostrar v22.x.x
npm --version     # Debería mostrar 10.x.x

4. Instalar herramientas de compilación

# Necesarias para compilar módulos nativos de npm
sudo apt install -y build-essential

Parte 2: Integración con CloudLinux CageFS

Contexto de CageFS

CageFS crea un sistema de archivos virtualizado para cada usuario, aislándolos del sistema real. Los binarios instalados en el sistema base no son visibles automáticamente dentro de las jaulas de los usuarios.

5. Registrar Node.js en CageFS

# Añadir nodejs como paquete conocido por CageFS
# Esto le indica a CageFS que debe copiar estos binarios al skeleton
cagefsctl --addrpm nodejs

Nota: El parámetro --addrpm funciona correctamente en Ubuntu aunque el nombre sugiera RPM. CageFS detecta automáticamente el gestor de paquetes del sistema.

6. Actualizar el skeleton de CageFS

# Forzar actualización del skeleton (estructura base de las jaulas)
cagefsctl --force-update

Salida esperada:

Copying /usr/bin/node to /usr/share/cagefs-skeleton/usr/bin/node
Creating symlink /usr/share/cagefs-skeleton/usr/bin/corepack to ../lib/node_modules/corepack/dist/corepack.js
Creating symlink /usr/share/cagefs-skeleton/usr/bin/npm to ../lib/node_modules/npm/bin/npm-cli.js
Creating symlink /usr/share/cagefs-skeleton/usr/bin/npx to ../lib/node_modules/npm/bin/npx-cli.js
Updating users ...
Updating user user1 ...
Updating user user2 ...
Updating user user3 ...

Qué hace este comando

  • Copia binarios: /usr/bin/node → /usr/share/cagefs-skeleton/usr/bin/node
  • Crea symlinks: npm, npx, corepack dentro del skeleton
  • Actualiza jaulas: Propaga los cambios a todos los usuarios enjaulados
  • Preserva aislamiento: Cada usuario ve su propia copia independiente

Verificación

7. Probar en usuario enjaulado

# Cambiar a un usuario con CageFS activo
su - user1

# Verificar disponibilidad de Node.js
node -v
# Output esperado: v22.11.0 (o versión actual de la rama 22.x)

npm -v
# Output esperado: 10.9.0 (o superior)

# Verificar ubicación (dentro de la jaula)
which node
# Output esperado: /usr/bin/node

8. Verificación adicional desde root

# Ver qué binarios están en el skeleton
ls -la /usr/share/cagefs-skeleton/usr/bin/ | grep node

# Verificar symlinks
ls -la /usr/share/cagefs-skeleton/usr/bin/{npm,npx,corepack}

# Ver usuarios con CageFS activo
cagefsctl --list-enabled

Troubleshooting

Node no visible dentro de CageFS

# Verificar que el usuario tiene CageFS activo
cagefsctl --user user1

# Forzar actualización de un usuario específico
cagefsctl --force-update-user user1

# Reinicializar completamente CageFS (último recurso)
cagefsctl --reinit

Permisos incorrectos

# Verificar permisos del binario en skeleton
ls -la /usr/share/cagefs-skeleton/usr/bin/node

# Debería ser ejecutable (755 o similar)
# Si no lo es:
chmod 755 /usr/share/cagefs-skeleton/usr/bin/node
cagefsctl --force-update

Actualización de Node.js

# Cuando NodeSource publique una nueva versión 22.x
sudo apt update
sudo apt upgrade nodejs

# IMPORTANTE: Después de actualizar, regenerar skeleton
cagefsctl --force-update

Diferencias Ubuntu vs CentOS/RPM

Aspecto Ubuntu (DEB) CentOS (RPM)
Instalación apt + NodeSource yum/dnf + NodeSource
Comando CageFS Mismo (--addrpm funciona) Mismo
Ubicación binarios /usr/bin/node /usr/bin/node
Documentación oficial Escasa para DEB Abundante para RPM
Funcionamiento Idéntico una vez instalado Idéntico

Notas importantes

  • Node 22 LTS tiene soporte hasta abril 2027
  • npm viene incluido con Node.js
  • CageFS es transparente para el usuario final
  • Actualizaciones automáticas: NodeSource mantiene la rama 22.x
  • Sin sudo para usuarios: Los usuarios no necesitan permisos especiales
  • Aislamiento preservado: Cada usuario ve su propia instancia

Resultado esperado

  • ✅ Node.js disponible en sistema base
  • ✅ Node.js disponible dentro de todas las jaulas CageFS
  • ✅ npm y npx funcionales para todos los usuarios
  • ✅ Actualizaciones automáticas del sistema afectan a todas las jaulas

Comandos de verificación rápida

# Desde root
node --version && npm --version

# Desde usuario enjaulado
su - user1 -c "node --version && npm --version"

# Listar paquetes registrados en CageFS
cagefsctl --list-packages | grep node

Validado en: Ubuntu 22.04 LTS con CloudLinux + CageFS
Fecha: Octubre 2025
Node.js: v22.11.0 LTS (Iron)

Aviso

Esta documentación y su contenido, no implica que funcione en tu caso o determinados casos. También implica que tienes conocimientos sobre lo que trata, y que en cualquier caso tienes copias de seguridad. El contenido el contenido se entrega, tal y como está, sin que ello implique ningún obligación ni responsabilidad por parte de Castris

Si necesitas soporte profesional puedes contratar con Castris soporte profesional.

Back to top