# 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)

```bash
# 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)

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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](https://castris.com)

Si necesitas soporte profesional puedes contratar con Castris [soporte profesional](https://intranet.castris.com/store/soporte-profesional).