База на знаења

En WizHosting podés correr aplicaciones Node.js (APIs, backends, SSR, etc.) usando el Selector de Node.js integrado con cPanel y CloudLinux.
No hace falta acceso root: todo se configura desde tu cuenta de cPanel.

En esta guía vamos a ver:

1. Requisitos y limitaciones.

2. Cómo preparar tu app Node.js.

3. Cómo crear la aplicación en cPanel (Setup Node.js App).

4. Cómo instalar dependencias (npm install) desde el panel.

5. Cómo configurar variables de entorno.

6. Cómo ver logs y errores.

7. Errores típicos y soluciones.

1. Requisitos y limitaciones

Antes de empezar, tené en cuenta:

• Necesitás un plan de hosting que incluya soporte para Node.js.

• El servidor corre CloudLinux + cPanel con el Selector de Node.js (Node.js App).

• No vas a escuchar en un puerto público (tipo 3000 abierto); el sistema hace un proxy interno desde Apache/Nginx hacia tu app Node, manejado automáticamente por el selector de aplicaciones.

Si en tu cPanel no ves la opción “Setup Node.js App” o “Node.js App” dentro de la sección Software, escribinos al soporte de WizHosting para que te confirmemos si tu plan actual soporta Node.

2. Preparar tu app Node.js

2.1. Estructura mínima recomendada

Tu proyecto debería tener como mínimo:

• Un archivo de entrada, por ejemplo: app.js, server.js o similar.

• Un package.json con un script start.

• Tus dependencias listadas (express, dotenv, etc.).

Ejemplo básico de package.json:

2.2. Escuchar el puerto correcto

En aplicaciones Node para hosting compartido no se usa un puerto fijo tipo 3000.
El selector de Node.js define un puerto interno y lo expone vía variable de entorno (PORT). Tu app tiene que respetarlo.

Ejemplo de app.js:

Si clavás el puerto a mano (por ejemplo app.listen(3000) sin usar process.env.PORT), el selector de aplicaciones puede no poder enrutar y el sitio no va a responder como corresponde.

3. Subir el código al servidor

Tenés dos caminos: FTP/SFTP o Administrador de archivos de cPanel.

3.1. Crear una carpeta para tu app

Recomendación:

1. Entrá a cPanel → File Manager / Administrador de archivos.

2. En tu home (/home/usuario), creá una carpeta para tus apps, por ejemplo:

   • nodeapps/mi-api

Así no mezclás el código con public_html.

3.2. Subir el proyecto

En tu PC:

1. Borrá node_modules (no lo vamos a subir).

2. Comprimí la carpeta del proyecto (mi-api) en un ZIP (por ejemplo mi-api.zip).

En cPanel:

1. Entrá a la carpeta nodeapps/mi-api.

2. Usá Upload / Cargar para subir mi-api.zip.

3. Una vez subido, seleccioná el ZIP y hacé clic en Extract / Extraer.

Al final deberías tener dentro de nodeapps/mi-api:

• app.js (o server.js)

• package.json

• el resto de tu código

pero sin node_modules.

4. Crear la aplicación Node.js en cPanel

1. Iniciá sesión en cPanel.

2. Andá a Software → Setup Node.js App (el nombre puede variar levemente según el tema de cPanel).

3. Hacé clic en Create Application.

4.1. Completar los datos de la app

En el formulario vas a ver varios campos. Los más importantes:

• Node.js version
  Elegí una versión compatible con tu proyecto (ej: 18.x, 20.x).

• Application mode
  Seleccioná Production para un sitio en producción.

• Application root
  Es la ruta dentro de tu cuenta hasta el código de la app, por ejemplo:
  nodeapps/mi-api

• Application URL
  Elegí el dominio o subdominio por el cual se va a acceder a la app, por ejemplo:

  • https://api.tudominio.com

  • o asigná un subdominio nuevo a este app root.

• Application startup file
  El archivo de entrada, por ejemplo:

  • app.js

  • server.js

Al completar todo, confirmá con Create / Create Application.

Esto le indica al servidor:

• Qué código ejecutar.

• En qué ruta de tu cuenta está el proyecto.

• A qué dominio o subdominio se debe apuntar.

5. Instalar dependencias con “Run NPM Install”

Una vez creada la app:

1. Volvé a Setup Node.js App y buscá la app que acabás de crear.

2. Hacé clic en el icono de editar (lápiz).

3. Dentro del detalle de la app, buscá el botón Run NPM Install o similar.

Eso va a ejecutar npm install dentro de la carpeta de la app, usando la versión de Node configurada y generando el directorio node_modules en el servidor, sin que tengas que subirlo vos.

Esperá a que termine el proceso (suele mostrar un log o al menos un mensaje de éxito/error).

6. Configurar variables de entorno (ENV)

Muchas APIs y backends usan variables para:

• Credenciales de base de datos.

• Claves de APIs.

• Secrets en general.

En la pantalla de configuración de la app Node.js vas a ver una sección llamada algo como Environment Variables o Variables de entorno.

1. Agregá las variables que necesites, por ejemplo:

   • NODE_ENV=production

   • DB_HOST=localhost

   • DB_NAME=mi_db

   • DB_USER=usuario_db

   • DB_PASS=contraseña_segura

2. Guardá cambios.

En tu código Node.js podés leerlas con process.env.NOMBRE_DE_LA_VAR, por ejemplo:

7. Iniciar y reiniciar la aplicación

En el detalle de la app Node.js vas a encontrar botones como:

• Start Application

• Stop Application

• Restart Application

Procedimiento típico:

1. Después de Run NPM Install, hacé clic en Start (si la app no está corriendo) o Restart (si ya estaba en marcha).

2. Esperá unos segundos.

3. Probá abrir el dominio o subdominio configurado (ej: https://api.tudominio.com).

Si todo está bien:

• Deberías ver la respuesta de tu API (JSON, mensaje “API funcionando”, etc.).

• En caso de error 500/503, revisá logs (ver siguiente punto).

8. Ver logs y errores

Dependiendo de la versión del panel, podés tener:

• Un botón View Logs dentro de la configuración de la app Node.

• Archivos de log creados en la carpeta de la app o en una ruta de logs de usuario.

Revisá especialmente:

• Errores de sintaxis en el código.

• Dependencias que no se pudieron instalar.

• Referencias a variables de entorno no definidas.

• Problemas típicos: no usar process.env.PORT, etc.

Si preferís, también podés loguear a archivo desde tu app con algún logger (p.ej. winston) o con console.log redirigidos.

9. Errores frecuentes y soluciones

9.1. La app no levanta / Service unavailable

Posibles causas:

• El archivo de inicio (startup file) está mal escrito (ej: app.js en el panel, pero el archivo se llama server.js).

• No se ejecutó Run NPM Install y faltan dependencias.

• El código hace app.listen(3000) en lugar de usar process.env.PORT.

Soluciones:

1. Revisar el nombre exacto del archivo de entrada.

2. Ejecutar Run NPM Install de nuevo.

3. Ajustar el listen para que use process.env.PORT.

9.2. Error “Cannot find module 'express'” u otros módulos

Causas:

• Dependencia no listada en package.json.

• npm install falló.

Soluciones:

1. En tu PC, asegurate de tener la dependencia en dependencies (no solo en devDependencies si se usa en producción).

2. Subí de nuevo el package.json actualizado.

3. Ejecutá otra vez Run NPM Install en cPanel.

9.3. Quiero actualizar el código de la app

Cada vez que cambies el código:

1. En tu PC, actualizá los archivos del proyecto.

2. Volvé a comprimir solo el código (sin node_modules) en un ZIP.

3. Subí y extraé en la misma carpeta de la app, sobrescribiendo archivos.

4. Si cambió package.json, ejecutá Run NPM Install.

5. Usá Restart Application desde el panel.

9.4. Necesito usar HTTPS

Del SSL se encarga el servidor web (Apache/Nginx) con Let’s Encrypt / AutoSSL.
Tu app Node.js no necesita manejar certificados directamente: recibe la conexión ya terminada por el proxy interno.

Solo asegurate de:

• Tener el certificado SSL activo para tu dominio/subdominio.

• Usar siempre URLs https:// en tus clientes.

10. ¿Cuándo NO usar Node.js en el hosting compartido?

Te conviene evaluar si realmente necesitás backend Node.js.
Si lo que tenés es:

• Una web React, Vue, etc. puramente del lado del cliente,
  generalmente es mejor subirla como sitio estático (ver Guía A), sin Node corriendo en el servidor.

Reservá Node.js para:

• APIs REST/GraphQL.

• SSR/Next.js en modo Node.

• Backends con lógica de negocio que sí necesitan runtime del lado del servidor.

11. Resumen rápido

1. Creá tu app Node con app.js/server.js y un package.json con script start.

2. Usá process.env.PORT para escuchar el puerto.

3. Subí el código a una carpeta tipo nodeapps/mi-api (sin node_modules).

4. En cPanel → Setup Node.js App → Create Application.

5. Configurá versión de Node, Application root, URL y startup file.

6. Ejecutá Run NPM Install.

7. Configurá variables de entorno si las necesitás.

8. Start/Restart y probá tu dominio/subdominio.

9. Revisá logs ante cualquier error.