Cómo instalar Node.js en Saplo (backend propio desde el repositorio)

Node.js no es un framework, sino un entorno de ejecución de JavaScript del lado del servidor. A diferencia de Next.js o Nuxt, la pila "Node.js" en el catálogo de Saplo no impone ninguna convención o estructura de proyecto. Puedes escribir tu propio servidor HTTP en Express, Fastify, Koa, NestJS o sin ningún framework, y Saplo solo se asegurará de que el proceso se ejecute continuamente y se reinicie después de un fallo. Esta es la opción más universal para el backend en el catálogo: se adapta a APIs para aplicaciones móviles, bots de Discord o servidores de websockets, siempre y cuando el proyecto exponga un puerto HTTP.

Para quién es Node.js en Saplo

Antes de empezar la instalación, comprueba si es la opción adecuada para tu proyecto:

• API para una aplicación móvil o frontend SPA - expones REST o GraphQL, y el frontend (React, Vue) lo configuras por separado desde el mismo directorio,
• bot o integración que funciona en segundo plano - webhooks, bots de Discord y Slack, workers de colas,
• backend para websockets - nginx en el lado de Saplo permite el encabezado Upgrade, por lo que las conexiones de larga duración funcionan sin configuración adicional,
• tienes un proyecto Node.js listo y quieres despliegues con git push - conectas el repositorio una vez, y Saplo construye y reinicia el proceso automáticamente.

Si tu proyecto está en un framework específico con su propia convención de construcción e inicio (Next.js, Nuxt), elige su stack dedicado en el catálogo - obtendrás una configuración lista para usar sin necesidad de especificar manualmente el comando de inicio.

Requisitos

Para instalar Node.js en Saplo, necesitas:

• Un Box en el plan L o superior: el proceso de Node se mantiene constantemente en la memoria, por lo que necesita más RAM que una página estática.
• Un mínimo de 512 MB de RAM libre y 3 GB de espacio en disco para el proceso de la aplicación.
• Un dominio o subdominio *.saploapp.pl incluido en el precio de cada plan.
• Un repositorio Git, si quieres utilizar la implementación automática (opcional para empezar, también puedes subir la aplicación como un archivo .zip a través del panel).

Instalación paso a paso

1. En el panel de Saplo, ve a Catálogo de aplicaciones y selecciona Node.js (categoría "Aplicaciones").
2. Indica un Box en el plan L o superior y el nombre de la aplicación; a partir de este se creará un subdominio por defecto.
3. Selecciona la versión de Node.js (18, 20 o 22, por defecto 20) y confirma la instalación.
4. El motor crea un starter mínimo de Express - package.json y server.js con un único endpoint - y lo ejecuta a través de un supervisor en el puerto 3000, mientras que nginx proxies el tráfico del dominio a ese puerto.
5. Una vez finalizada la instalación, el dominio del paso 2 muestra el starter funcionando; a partir de este momento, lo reemplazas con tu propio código a través de git deploy.

Despliegue de tu propio código a través de Git

1. En los detalles de la aplicación, encuentra la sección Git / CI-CD y haz clic en "Conectar GitHub", confirma la instalación de la aplicación "Saplo Deploy" e indica el repositorio con tu proyecto Node.
2. En el directorio raíz del repositorio, coloca el archivo saplo.yaml. A diferencia de los stacks con una convención específica (Next.js, Nuxt), el stack Node.js no tiene un comando de inicio por defecto: debes especificar explícitamente start.command; de lo contrario, la compilación tendrá éxito, pero el proceso no se iniciará.
3. Confirma y envía el archivo a la rama de producción (por defecto main).
4. Cada git push posterior a esta rama inicia la compilación y reinicia el proceso; puedes ver el estado en la pestaña Despliegues.
5. El puerto predeterminado de la aplicación es 3000; nginx redirige el tráfico de 80/443 a este puerto, a menos que lo cambies en start.port.

Ejemplo de un archivo saplo.yaml mínimo para Node.js:

name: my-project
stack: node
runtime:
  node: "22"
build:
  install: npm ci
start:
  command: node index.js
  port: 3000
env:
  NODE_ENV: production

Node.js en Saplo vs. alternativas

Preguntas frecuentes

¿Funciona cualquier framework (Express, Fastify, NestJS)? Sí, el stack de Node.js no impone un framework. Solo requiere que el proceso escuche en el puerto especificado en start.port (3000 por defecto).

¿Qué pasa si olvido start.command en saplo.yaml? La compilación se realizará correctamente, pero el proceso no se iniciará. Verás el error en la pestaña Despliegues. Añade start.command y envía una nueva versión.

¿Funcionan los websockets a través de nginx de Saplo? Sí, el proxy inverso permite el encabezado Upgrade, por lo que las conexiones WebSocket de larga duración funcionan sin configuración adicional.

¿Puedo tener una base de datos junto a la aplicación? Sí, puedes crear la base de datos (Postgres, MySQL, Redis) como una aplicación separada desde el catálogo y vincular la variable de conexión en env de tu saplo.yaml.

¿Obtendré SSL y mi propio dominio? Sí, el certificado SSL es automático, y el dominio o subdominio *.saploapp.pl está incluido en el precio de cada plan.

En Saplo, puedes configurar Node.js desde cero hasta un dominio funcional en cuestión de minutos, y cada git push posterior reinicia el proceso con la nueva versión sin tu intervención. Si tu proyecto utiliza un framework específico con su propia convención (Next.js, Nuxt), consulta su stack dedicado en el mismo directorio.