Cómo desplegar una aplicación Node.js en hosting cPanel
Node.js es uno de los entornos de ejecución más populares para construir aplicaciones web, APIs y herramientas de automatización con JavaScript en el servidor. Y aunque muchos desarrolladores asumen que necesitan un VPS para correrlo, la realidad es que cualquier hosting cPanel moderno incluye soporte para Node.js a través de la herramienta Setup Node.js App, lo que permite desplegarlo directamente desde el panel sin tocar la línea de comandos.
En esta guía te explico el proceso completo: desde preparar tu aplicación en local hasta tenerla corriendo en producción, pasando por los errores más frecuentes y cómo resolverlos.
Qué es Setup Node.js App y cómo funciona en cPanel
Setup Node.js App es la herramienta integrada en cPanel que permite crear y gestionar aplicaciones Node.js sin necesidad de acceso root ni configuración manual del servidor. Está disponible en todos los planes de hosting compartido de BlumHost.
Lo que hace por ti es:
- Crear un entorno Node.js aislado para tu aplicación con la versión que elijas
- Configurar el proxy inverso para que tu dominio apunte a tu app
- Gestionar el ciclo de vida de la aplicación (inicio, parada, reinicio)
- Permitir instalar dependencias npm y ejecutar scripts del
package.json - Administrar variables de entorno de forma segura
Internamente, cPanel usa Phusion Passenger como servidor de aplicaciones, que actúa de puente entre el servidor web (Apache o LiteSpeed) y tu proceso Node.js. Esto significa que no tienes que preocuparte por los puertos: tu app escucha a través de un socket Unix y el servidor web enruta el tráfico automáticamente.
Antes de empezar: prepara tu aplicación en local
Antes de subir nada al servidor, tu aplicación debe estar en un estado listo para producción. Comprueba estos puntos:
El archivo de entrada existe y es correcto. Necesitas un archivo .js que arranque el servidor — habitualmente app.js, server.js o index.js. Este será el que cPanel ejecute al iniciar la aplicación.
Tienes un package.json en la raíz del proyecto. Este archivo es obligatorio: cPanel lo usa para instalar las dependencias con npm install.
Las dependencias están listadas en package.json. Todo lo que uses debe estar declarado en dependencies (no solo en devDependencies). Si una librería solo está en devDependencies, no se instalará cuando ejecutes npm install en el servidor.
Tu aplicación no escucha en un puerto fijo. En cPanel con Passenger, el puerto lo asigna el sistema. La forma correcta de escribirlo es:
javascript
const port = process.env.PORT || 3000;
app.listen(port, () => {
console.log(`Servidor escuchando en el puerto ${port}`);
});Passenger inyecta automáticamente la variable PORT con el valor correcto. Si tu app intenta escuchar en un puerto fijo como el 80 o el 3000, fallará en cPanel.
La carpeta node_modules no va al servidor. Nunca subas node_modules: ocupa cientos de megas y las dependencias nativas deben recompilarse para la arquitectura del servidor. Compila las dependencias directamente en cPanel usando el botón de npm install.
Paso a paso: desplegar Node.js en cPanel
Paso 1 — Sube los archivos al servidor
Accede al Administrador de archivos de cPanel y crea una carpeta para tu aplicación dentro de tu directorio home. Por ejemplo: mi-app-node.
Sube ahí todos los archivos de tu proyecto excepto node_modules. Las opciones para subir los archivos son:
- Administrador de archivos → Cargar (arrastra un
.zipy luego extrae) - FTP con Filezilla o similar
- SSH con
scpsi tienes acceso habilitado
Si subes un .zip, una vez extraído verás la estructura de tu proyecto dentro de la carpeta que hayas creado.
Paso 2 — Accede a Setup Node.js App
En el panel principal de cPanel, localiza la sección Software y haz clic en Setup Node.js App.
Verás el listado de aplicaciones Node.js activas en tu cuenta. La primera vez estará vacío. Haz clic en Create Application.
Paso 3 — Configura la aplicación
El formulario de creación tiene cinco campos principales:
Node.js version Selecciona la versión de Node.js que necesita tu aplicación. Si no tienes un requisito específico, elige la versión LTS más reciente disponible. Las versiones LTS (Long Term Support) son las más estables y las que reciben actualizaciones de seguridad durante más tiempo.
Para saber qué versión usas en local, ejecuta node --version en tu terminal y selecciona la misma en cPanel para evitar incompatibilidades.
Application mode Dos opciones: development o production.
- En development, Node.js muestra mensajes de error detallados y recarga algunos elementos automáticamente. Útil para depurar problemas durante el despliegue inicial.
- En production, los mensajes de error no se exponen al usuario, el rendimiento mejora y el comportamiento es el correcto para una web real.
Empieza con development para verificar que todo funciona, y cámbialo a production una vez que la aplicación responda correctamente.
Application root La ruta al directorio donde están los archivos de tu aplicación, relativa a tu carpeta home. Si subiste los archivos a /home/tuusuario/mi-app-node/, en este campo escribes simplemente mi-app-node.
Application URL La URL desde la que será accesible tu aplicación. Puedes elegir:
| Opción | Ejemplo |
|---|---|
| Dominio raíz | tudominio.com |
| Subdominio | api.tudominio.com |
| Ruta del dominio | tudominio.com/app |
Si usas un subdominio, créalo primero desde cPanel → Dominios antes de configurarlo aquí.
Application startup file El archivo JavaScript que Node.js ejecutará al arrancar. Escribe el nombre del archivo sin ruta, por ejemplo app.js o server.js. Debe existir en el directorio que indicaste en Application root.
Paso 4 — Crea la aplicación
Haz clic en Create. cPanel configurará el entorno y la aplicación aparecerá en el listado con estado Running.
Para verificar que funciona, abre la URL que configuraste en el navegador. Si tu aplicación arranca sin errores, la verás respondiendo.
Paso 5 — Instala las dependencias npm
Desde el listado de aplicaciones, haz clic en el icono de edición de tu app para entrar a la pantalla de gestión.
Aquí encontrarás el botón Run NPM Install. Haz clic en él para que cPanel ejecute npm install en el directorio de tu aplicación e instale todas las dependencias declaradas en package.json.
Espera a que termine — dependiendo del número de paquetes puede tardar entre unos segundos y varios minutos. Cuando acabe, verás el resultado de la instalación en el log que aparece en pantalla.
Paso 6 — Reinicia y verifica
Después de instalar las dependencias, haz clic en Restart para reiniciar la aplicación con las dependencias ya instaladas.
Accede de nuevo a la URL de tu aplicación. Si todo está correcto, tu app Node.js estará funcionando en producción.
Configurar variables de entorno
Si tu aplicación usa un archivo .env para credenciales de base de datos, claves de API u otras configuraciones, puedes gestionarlas directamente desde cPanel sin crear el archivo manualmente.
En la pantalla de gestión de tu aplicación, desplázate hasta la sección Environment Variables. Aquí puedes añadir pares clave-valor que estarán disponibles en tu aplicación a través de process.env.
Por ejemplo:
| Variable | Valor |
|---|---|
DATABASE_URL | mysql://usuario:pass@localhost/mibd |
API_KEY | sk_live_... |
NODE_ENV | production |
Después de añadir o modificar variables de entorno, haz clic en Restart para que la aplicación las cargue.
Ventaja respecto al archivo .env: las variables configuradas aquí no están en los archivos del proyecto, así que no pueden acabar en un repositorio Git por accidente.
Ejecutar scripts npm personalizados
Además de npm install, cPanel permite ejecutar cualquier script definido en la sección scripts de tu package.json.
Por ejemplo, si tienes un script de build:
json
{
"scripts": {
"build": "tsc --outDir dist",
"migrate": "node scripts/migrate.js"
}
}Desde la pantalla de gestión de la aplicación verás estos scripts disponibles en un desplegable. Puedes ejecutarlos directamente desde el panel sin necesidad de SSH.
Esto es especialmente útil para aplicaciones TypeScript (donde necesitas compilar antes de iniciar), proyectos con migraciones de base de datos, o cualquier tarea de preparación que requiera ejecutarse tras un despliegue.
Cómo actualizar la aplicación después del despliegue
El flujo para actualizar una aplicación ya desplegada es:
- Sube los archivos actualizados al mismo directorio de la aplicación (por FTP, Administrador de archivos o SSH)
- Si has añadido o eliminado dependencias npm, ejecuta Run NPM Install de nuevo
- Si tienes scripts de build, ejecuta el script correspondiente
- Haz clic en Restart para que la aplicación recargue el código
Node.js no recarga el código automáticamente al detectar cambios en los archivos — siempre necesitas reiniciar manualmente desde el panel o mediante SSH.
Errores frecuentes y cómo resolverlos
Error 503 o «Application Not Started» al acceder a la URL
La aplicación no está en estado Running. Causas más comunes:
- El startup file no existe en el directorio de la aplicación. Verifica que el archivo indicado (por ejemplo
app.js) está realmente en el Application root. - La aplicación falla al arrancar por un error de código. Activa el modo
developmenttemporalmente y revisa el log de errores de cPanel para ver el mensaje de error completo. - Las dependencias no están instaladas. Ejecuta Run NPM Install desde la pantalla de gestión.
Para ver el log de errores: cPanel → Métricas → Errores, o consulta el archivo de log específico de la aplicación que cPanel genera en el directorio de la app.
La aplicación funciona en local pero falla en cPanel
Las causas más habituales son:
- Versión de Node.js diferente. Comprueba qué versión usas en local con
node --versiony asegúrate de seleccionar la misma en cPanel. - Puerto fijo en el código. Si tu aplicación escucha en un puerto específico con
app.listen(3000), en cPanel fallará porque Passenger gestiona el puerto. Usaprocess.env.PORT || 3000como se indicó antes. - Módulos nativos. Si algún paquete npm incluye código nativo en C++, necesita recompilarse en el servidor. Al ejecutar
npm installdesde cPanel esto sucede automáticamente, pero asegúrate de no subir la carpetanode_modulesde tu máquina local. - Rutas absolutas de archivos. Si tu código usa rutas absolutas que solo existen en tu máquina, fallará en el servidor. Usa siempre
__dirnameo rutas relativas.
npm install falla o da errores de permisos
Verifica que:
- El archivo
package.jsonexiste en el Application root (no en una subcarpeta) - No hay una carpeta
node_modulesde una instalación previa — si la hay, elimínala desde el Administrador de archivos y vuelve a ejecutar npm install - La versión de Node.js seleccionada es compatible con las dependencias de tu proyecto
Los cambios en el código no aparecen en la web
Node.js no tiene recarga automática en producción. Después de modificar archivos, siempre haz clic en Restart desde la pantalla de gestión de la aplicación.
Ejemplo completo: API REST con Express en cPanel
Para hacer esto concreto, aquí tienes el código mínimo de una API con Express que funciona correctamente en cPanel:
package.json
json
{
"name": "mi-api",
"version": "1.0.0",
"description": "API REST de ejemplo",
"main": "app.js",
"scripts": {
"start": "node app.js"
},
"dependencies": {
"express": "^4.18.0"
}
}app.js
javascript
const express = require('express');
const app = express();
app.use(express.json());
app.get('/', (req, res) => {
res.json({
mensaje: 'API funcionando correctamente',
version: process.version
});
});
app.get('/salud', (req, res) => {
res.json({ estado: 'ok', timestamp: new Date().toISOString() });
});
// Importante: usar process.env.PORT para que funcione con Passenger/cPanel
const port = process.env.PORT || 3000;
app.listen(port, () => {
console.log(`API escuchando en el puerto ${port}`);
});Con este código, la configuración en cPanel sería:
- Application root: la carpeta donde subiste estos archivos
- Application startup file:
app.js - Application URL: tu dominio o subdominio
Después de crear la app y ejecutar npm install, la API responderá en la URL que hayas configurado.
Qué plan de BlumHost necesitas para Node.js
Node.js está disponible en todos los planes de hosting compartido de BlumHost. La herramienta Setup Node.js App viene incluida en cPanel sin coste adicional.
| Plan | RAM | Almacenamiento | Para qué es adecuado |
|---|---|---|---|
| Web Hosting I | 1 GB | 5 GB NVMe | APIs pequeñas, proyectos en pruebas |
| Web Hosting II | 3 GB | 10 GB NVMe | Aplicaciones con tráfico moderado |
| Web Hosting III | 6 GB | 20 GB NVMe | Múltiples apps o aplicaciones con más carga |
Para proyectos con alta concurrencia, procesamiento intensivo o necesidad de queue workers persistentes (tareas en segundo plano), un VPS es la opción más adecuada: tienes control total sobre la configuración del servidor y puedes usar PM2 o systemd para gestionar el proceso Node.js.
👉 Ver todos los planes de hosting de BlumHost
Preguntas frecuentes
¿Puedo tener varias aplicaciones Node.js en el mismo hosting? Sí. Puedes crear múltiples aplicaciones, cada una con su propia URL (dominio, subdominio o ruta), su versión de Node.js y sus dependencias independientes. El número de aplicaciones que puedes tener depende de los recursos de tu plan.
¿Qué versiones de Node.js están disponibles? Las versiones disponibles dependen de las instaladas en el servidor en cada momento. Puedes verlas directamente en el selector al crear la aplicación. Si necesitas una versión específica que no aparece, contacta con soporte.
¿Puedo usar TypeScript, Next.js o Nuxt en hosting cPanel? TypeScript: sí, pero necesitas compilar el código TypeScript a JavaScript antes de desplegarlo (localmente con tsc) y subir los archivos .js resultantes. Next.js y Nuxt en modo SSR (renderizado en servidor) requieren más configuración y son más adecuados para un VPS. En hosting compartido puedes desplegar sus versiones exportadas como sitios estáticos.
¿Cómo gestiono los logs de mi aplicación? Desde cPanel → Métricas → Errores puedes ver los errores de tu aplicación. Además, si tu aplicación escribe logs propios a un archivo, puedes consultarlos desde el Administrador de archivos. En mode development, los errores de Node.js aparecen también en los logs del servidor web.
¿Puedo conectarme a una base de datos MySQL desde mi aplicación Node.js? Sí. Crea primero la base de datos y el usuario desde cPanel → Bases de datos MySQL. Luego usa en tu aplicación Node.js el paquete mysql2 o el ORM que prefieras (Sequelize, Prisma, etc.) con host: 'localhost'. Configura las credenciales a través de las variables de entorno de la aplicación para no exponerlas en el código.
¿Necesito SSH para desplegar Node.js en cPanel? No es imprescindible. Todo el proceso — crear la aplicación, instalar dependencias, configurar variables de entorno, reiniciar — se hace desde la interfaz de cPanel sin línea de comandos. SSH es útil si quieres ejecutar scripts personalizados o depurar problemas directamente en el servidor.
¿Puedo usar WebSockets con Node.js en hosting cPanel? Depende de la configuración del servidor. Passenger (que es lo que usa cPanel) tiene soporte para WebSockets, pero puede haber restricciones a nivel de proxy. Para aplicaciones que dependan mucho de WebSockets en tiempo real, un VPS con configuración propia es más recomendable.
