Desplegando una aplicación Node.js en hosting compartido de cPanel con Passenger

Muchos hosts compartidos de cPanel pueden ejecutar bien una aplicación Express o un servidor API, siempre y cuando la cuenta cuente con soporte para Node.js junto con Phusion Passenger detrás del Administrador de aplicaciones de cPanel. No es necesario configurar Nginx, un proxy inverso Apache ni PM2 por cuenta propia; Passenger inicia la aplicación y dirige las solicitudes hacia ella. Esta guía abarca el despliegue completo, desde verificar que la función esté habilitada hasta diagnosticar un error 503, y finaliza con una lista de verificación previa al lanzamiento.

Requisitos de su cuenta de hosting

Asegúrese de que la cuenta ofrezca lo siguiente antes de subir cualquier cosa:

• Soporte para Node.js
• Administrador de aplicaciones de cPanel
• Passenger
• Acceso a la terminal o SSH
• npm
• Un dominio o subdominio desde el cual servir la aplicación
• Acceso a una base de datos, si la aplicación lo requiere

Si falta Application Manager, pídale a su proveedor que active Node.js y Passenger. Los proveedores que utilizan CloudLinux pueden denominar la herramienta de manera diferente.

Paso 1: Confirmar que Node.js está disponible

En cPanel, abra Software y luego Application Manager (algunas versiones muestran las opciones de Node.js bajo administración del sitio web en su lugar). Si se abre, la cuenta está lista.

Paso 2: Subir la aplicación

Suba el proyecto mediante el Gestor de archivos o Git a una carpeta en su directorio personal, por ejemplo:

/home/username/my-node-app

Un layout típico de proyecto se ve así:

my-node-app/
├── package.json
├── package-lock.json
├── app.js
├── src/
└── ...

Mantenga el código fuente fuera de public_html, ya que los navegadores pueden solicitar directamente cualquier archivo que se encuentre allí.

Paso 3: Preparar package.json e instalar dependencias

El proyecto necesita un package.json válido que declare sus dependencias y una secuencia de inicio. Un ejemplo mínimo con Express:

{
  "name": "my-node-app",
  "version": "1.0.0",
  "scripts": {
    "start": "node app.js"
  },
  "dependencies": {
    "express": "^5.1.0"
  }
}

Luego abra la Terminal de cPanel, vaya a la carpeta del proyecto e instale:

cd ~/my-node-app
npm install

Esto instala las dependencias declaradas en el servidor. Con un archivo de bloqueo guardado, npm ci --omit=dev es una alternativa más ligera y reproducible.

Paso 4: Escribir el archivo de inicio

Passenger necesita un punto de entrada que pueda ejecutar, como por ejemplo:

app.js

En una aplicación Express, ese archivo comienza cargando Express:

const express = require('express');

y luego crea la aplicación, define una ruta y comienza a escuchar. El código a continuación está condensado en unas pocas líneas, pero es un JavaScript válido porque cada declaración termina con un punto y coma.

const app = express();const PORT = process.env.PORT || 3000;app.get('/', (req, res) => {
    res.send('Node.js application is working!');
});app.listen(PORT, '0.0.0.0', () => {
    console.log(`Application running on port ${PORT}`);
});

Por qué el puerto debe provenir de process.env.PORT

No codifique de forma fija un puerto público. Passenger decide cómo llegan las solicitudes a su proceso, por lo que debe leer el puerto del entorno y mantener una opción de respaldo local:

const PORT = process.env.PORT || 3000;

El mismo código se ejecuta entonces localmente en el puerto 3000 y con Passenger sin cambios.

Paso 5: Registrar la aplicación en cPanel

En Application Manager, haga clic en Create Application o Register Application. Asigne un nombre a la aplicación, como my-node-app, elija el dominio (por ejemplo example.com) y / como URL base, establezca la carpeta raíz en la carpeta del proyecto y el archivo de inicio en app.js, elija una versión estable de Node.js que soporten sus dependencias, y seleccione el entorno Production. Luego haga clic en Create o Deploy. La ruta de la solicitud resultante se verá así:

https://example.com
       ↓
     Apache
       ↓
    Passenger
       ↓
   Node.js App
       ↓
     app.js

Apache recibe la solicitud, y Passenger la reenvía al proceso de Node.js iniciado desde su archivo de inicio.

Paso 6: Establecer variables de entorno

Defina las variables de entorno en la configuración de la aplicación en lugar de en el código. Por ejemplo:

APP_ENV=production
DB_HOST=localhost
DB_DATABASE=mydb
DB_USERNAME=myuser
DB_PASSWORD=your_password

Su código los lee a través de process.env:

process.env.DB_HOST
process.env.DB_DATABASE
process.env.DB_USERNAME

Mantenga los datos confidenciales únicamente en el lado del servidor: nunca en JavaScript del frontend ni en un archivo accesible públicamente como un .env en public_html.

Paso 7: Reinicie después de cada cambio

Passenger mantiene la aplicación cargada, por lo que los cambios solo se aplican después de un reinicio desde Application Manager. Donde se admite la convención de archivo de reinicio, también funciona la terminal:

mkdir -p ~/my-node-app/tmp
touch ~/my-node-app/tmp/restart.txt

Passenger monitorea la marca de tiempo de tmp/restart.txt y reinicia la aplicación en la siguiente solicitud después de que cambie, lo cual es adecuado para scripts de despliegue.

Resolución de problemas de 503 Servicio no disponible

El error que más probablemente encontrará es este:

503 Service Unavailable

Un 503 rara vez significa que el servidor está caído; generalmente Passenger no pudo iniciar o acceder a su aplicación. Pruebe ejecutarla usted mismo primero:

cd ~/my-node-app
node app.js

Si falla, arregle eso primero. Si arranca, revise los problemas más comunes.

Archivo de inicio incorrecto

El Administrador de Aplicaciones debe apuntar al archivo que realmente existe y que inicia el servidor:

app.js

Dependencias faltantes

Si node_modules está ausente o incompleto, instálelo nuevamente:

npm install

Versión incompatible de Node.js

Verifique qué versión está utilizando la terminal y cuáles son los requisitos de sus dependencias:

node -v

Luego elija una versión compatible en la configuración de la aplicación.

Porto codificado de forma fija

Asegúrese de que el servidor escuche en:

process.env.PORT

en lugar de un puerto público fijo.

Variables de entorno faltantes

Confirme que las credenciales, claves API, el modo de la aplicación y otros valores necesarios estén configurados; una variable no definida que provoque un fallo en el inicio también genera un 503.

Registros

Los registros del Passenger o de la aplicación cPanel suelen mostrar el error exacto al iniciar.

Alojamiento compartido versus VPS

Los dos entornos difieren principalmente en quién controla el servidor. En el alojamiento compartido con cPanel, la estructura es más o menos así:

cPanel
   │
   ├── Apache
   ├── Passenger
   └── Node.js
          │
          └── Your Application

El proveedor de hosting y Passenger gestionan el servidor web y los procesos. En un VPS, uno tiene control total sobre cada capa:

VPS
 │
 ├── Nginx/Apache
 ├── Node.js
 ├── PM2
 ├── Firewall
 ├── SSL
 └── Application

Un VPS ofrece mucho más control y generalmente es más adecuado para aplicaciones que requieren muchos recursos o están altamente personalizadas; consulte un marco práctico para llevar aplicaciones Node.js a producción. El alojamiento compartido sacrifica ese control en favor de la simplicidad.

Estructura de directorios ordenada

Una implementación limpia con cPanel mantiene la aplicación y la raíz web pública una al lado de la otra:

/home/username/
│
├── my-node-app/
│   ├── app.js
│   ├── package.json
│   ├── package-lock.json
│   ├── node_modules/
│   ├── src/
│   └── tmp/
│       └── restart.txt
│
└── public_html/

Las solicitudes llegan a my-node-app a través de Apache y Passenger, y public_html permanece libre de código del servidor.

Lista de verificación final

Antes de considerar que el despliegue está completo, confirme que:

• Node.js está habilitado para la cuenta
• El Application Manager está disponible
• Se ha seleccionado una versión compatible de Node.js
• Los archivos del proyecto se han subido fuera de public_html
• Está presente package.json
• npm install se completó sin errores
• La configuración del archivo de inicio es correcta
• El servidor escucha en process.env.PORT
• Las variables de entorno están configuradas
• El entorno está establecido en Producción
• La aplicación se ha reiniciado desde el último cambio
• El dominio se carga en un navegador

los registros no muestran errores de inicio

Conclusión

En el hosting compartido de cPanel, Application Manager con Passenger es la opción fiable que permite ejecutar aplicaciones y APIs de Express sin acceso root. Deje que Passenger controle el puerto, reinicie después de cada cambio y, cuando algo falle, ejecute la aplicación manualmente y lea los registros antes de modificar la configuración.