Crear y configurar una aplicación Astro con Setup Node.js App

Actualizado hace 5 días

Las aplicaciones Astro se ejecutan en tu hosting a través del Node.js Selector de CloudLinux: en cPanel, la opción Setup Node.js App crea la aplicación, instala sus dependencias y la deja corriendo bajo tu dominio. Esta guía recorre el proceso completo: preparar el proyecto con el adaptador de Node, crear la aplicación, subir el código, compilar y administrarla.

Preparar tu proyecto Astro

Para que Astro sirva páginas renderizadas bajo demanda desde el servidor, el proyecto necesita el adaptador oficial @astrojs/node en modo standalone. Podés agregarlo desde tu proyecto con npx astro add node, o configurarlo a mano en astro.config.mjs:

import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  adapter: node({
    mode: 'standalone',
  }),
});

Si tu sitio es totalmente estático no necesitás Node: compilalo localmente y subí los archivos generados como cualquier sitio. El resto de esta guía aplica a proyectos que usan el adaptador de Node.

Crear la aplicación

La aplicación se registra desde cPanel, en la sección Software.

Ingresa a tu cPanel y, en la sección Software, haz clic en Setup Node.js App.
Haz clic en CREAR APLICACIÓN.
En Versión de Node.js, elegí la versión más alta disponible que cumpla el requisito de tu proyecto. El desplegable muestra las versiones habilitadas en tu servidor y marca la recomendada. Astro requiere Node 22.23.4 o superior (las versiones impares, como la 23, no están soportadas); verificá el requisito vigente en la documentación de Astro.
En Raíz de aplicación, escribí la carpeta donde va a vivir el código, por ejemplo adhoc-app. Esa es la ruta física dentro de tu cuenta donde después vas a subir los archivos del proyecto.
En URL de la aplicación, elegí el dominio o subdominio y completá la URI donde se va a acceder a la aplicación; si querés servirla en un subdirectorio de ese dominio, agregalo ahí.
En Modo de aplicación, elegí Production para un sitio en producción: esta opción establece el valor de la variable NODE_ENV, y el panel la trae en Development por defecto.
En Archivo de inicio de la aplicación, escribí dist/server/entry.mjs: es el archivo que el adaptador de Node genera al compilar y que arranca el servidor. La ruta es relativa a la Raíz de aplicación.
Haz clic en CREATE. La aplicación queda registrada y aparece en la lista con su estado.

No uses public_html como Raíz de aplicación: una aplicación Node incluye archivos de configuración y credenciales (como .env) que no deben quedar expuestos en la web. Creá una carpeta propia para la aplicación.

Subir tu código

El selector no sube el código por ti: subí los archivos de tu proyecto a la carpeta que definiste como Raíz de aplicación, desde el Administrador de archivos, por FTP o por SSH. Si tenés el repositorio en GitHub, GitLab o similar, podés clonarlo directo desde cPanel:

En cPanel, abrí Git Version Control, dentro de la sección Files, y creá un nuevo repositorio.
Dejá activada la opción Clone a repository, pegá la URL de clonado de tu repositorio y, en el camino del repositorio, poné la carpeta que definiste como Raíz de aplicación.
Confirmá la creación y verificá en el Administrador de archivos que los archivos del proyecto estén en la carpeta.

Si el repositorio tiene más ramas, podés cambiar la rama activa desde la configuración del repositorio. Esto también permite clonar el mismo repositorio dos veces en carpetas distintas, por ejemplo para un entorno de pruebas en un subdominio.

Instalar dependencias y compilar

La aplicación necesita dos comandos para funcionar: npm install para las dependencias y npm run build para generar el servidor. Podés lanzarlos desde el panel o desde SSH.

Desde el panel

En Setup Node.js App, abrí tu aplicación desde la lista (icono de lápiz).
Haz clic en Run NPM Install y esperá a que termine.
Haz clic en Run JS Script y elegí el script build de tu package.json.

Desde SSH

Cada aplicación tiene su propio entorno virtual de Node. Entrá por SSH (o desde Terminal, en la sección Avanzado de cPanel) y ejecutá el comando para entrar al entorno virtual que muestra la página de tu aplicación. Tiene el formato:

source /home/TUUSUARIO/nodevenv/aplicacion/22/bin/activate && cd /home/TUUSUARIO/aplicacion

Copialo tal cual desde el panel, porque incluye tu usuario, tu carpeta y la versión de Node elegida. Para confirmar que estás dentro del entorno, ejecutá node -v: tiene que devolver la versión que seleccionaste al crear la aplicación. Después ejecutá npm install y, cuando termine, npm run build.

Al terminar, abrí el dominio que configuraste en URL de la aplicación: deberías ver tu sitio funcionando.

Variables de entorno

En la sección Environment variables de tu aplicación, haz clic en AÑADIR VARIABLE, completá el nombre y el valor de cada variable y guardala con su botón de confirmación: las que no quedan guardadas no se aplican. Ni Astro ni el adaptador de Node cargan las variables de un archivo .env al servir el sitio en el servidor, así que si tu proyecto lee variables en tiempo de ejecución, definilas ahí. Podés editarlas o agregar más cuando quieras.

Si al ejecutar comandos de npm aparecen errores de proceso en ejecución o de recursos, probá agregar la variable de entorno RAYON_NUM_THREADS con el valor 1 y reiniciar la aplicación.

Reiniciar y actualizar

Después de modificar código, dependencias o variables de entorno, reiniciá la aplicación para que cargue los cambios. La lista de aplicaciones muestra el estado de cada una: started con la versión de Node entre paréntesis, y botones para detener, reiniciar, editar y eliminar.

El flujo de actualización es el mismo que en cualquier servidor propio: hacé y probá los cambios en tu entorno local, subilos al repositorio, traelos al servidor con git pull (o con el botón de actualizar del repositorio en cPanel), volvé a ejecutar npm install si cambiaste dependencias, compilá con npm run build y reiniciá la aplicación.

Si algo falla

Al abrir Setup Node.js App aparece The received data is wrong. Contact support for resolution. cagefs_enter: Unable to fork: llegaste al límite de procesos en simultáneo que permite tu plan. Revisá el consumo en Uso de Recursos, dentro de cPanel; te contamos cómo resolverlo en Error con NodeJS: The received data is wrong. Contact support for resolution. cagefs_enter: Unable to fork.
La aplicación devuelve errores 500 o 503, o responde lenta: puede que haya alcanzado los límites de recursos de tu plan, como la memoria o la cantidad de procesos. Cómo funcionan esos límites lo explicamos en Administrar recursos y límites con CloudLinux Manager.

Nosotros administramos la infraestructura, el panel y el selector; el código, las dependencias y las actualizaciones de tu aplicación quedan de tu lado. Si el error persiste, escribinos por WhatsApp o desde el área de clientes y lo revisamos.

¿Te fue útil?