Cómo Desplegar Astro en un VPS con CloudPanel (Guía 2026)

Desplegar Astro en un VPS con CloudPanel te da lo único que las plataformas gratuitas nunca ofrecen: control total. Tu build, tus cabeceras de caché, tu ruta de rollback y sin límites de minutos de build esperando para sorprenderte a final de mes. El hosting gratuito como Cloudflare Pages, Vercel y Netlify funciona bien hasta que deja de hacerlo: límites de ancho de banda, límites de build o lock-in de plataforma.

CloudPanel es un panel de hosting gratuito que corre sobre Nginx. Gestiona la administración de sitios, el SSL y el aislamiento de usuarios a través de una interfaz web. Despliegas Astro como un Static HTML site y dejas que CloudPanel sirva los archivos compilados directamente desde Nginx. Ningún proceso de Node.js corre en runtime, lo que significa que un VPS pequeño y barato es suficiente. Y desde que Astro 7 salió en junio de 2026 con builds entre un 15 y un 61 % más rápidos (nuestro benchmark de builds de Astro 7), los rebuilds en esa máquina pequeña son más rápidos que antes.

Los precios de los VPS subieron en todos los proveedores en 2026. Si estás replanteándote una máquina alquilada, mira qué cambió y cuándo gana un mini PC.

Prerequisitos

Antes de empezar, esto es lo que ya tiene que existir:

El stack que monta esta guía: VPS Linux + CloudPanel (Nginx) + NVM + Node 24 + Cloudflare delante. Todo lo demás es opcional.

También puedes desplegar Astro en un VPS con Coolify o EasyPanel si prefieres otro panel. Para stacks pesados en Docker son buenas opciones. Para un sitio Astro puramente estático, CloudPanel es el camino más simple.

Si quieres monitorizar CPU, memoria y espacio en disco de tu servidor, mira: Cómo monitorizar recursos de servidor y Docker

Videoguía

Desplegar Astro.js en un VPS con CloudPanel

Hay dos enfoques en CloudPanel: un Static HTML site (recomendado para salida puramente estática) o un Node.js site. El enfoque Static HTML es más simple y barato de correr: CloudPanel sirve los archivos compilados directamente desde Nginx sin ningún proceso Node.js en runtime. Esta es la secuencia completa: sitio, DNS, SSL, Node para compilar, proyecto, build y automatización.

Paso 1: Añade un sitio Static HTML en CloudPanel

1. Inicia sesión en tu panel de administración de CloudPanel.
2. Ve a Sites > Add Site > Create a Static HTML Site. (La documentación actual de CloudPanel para todos los tipos de sitio está en cloudpanel.io/docs/v2/frontend-area/add-site/.)
3. Introduce tu nombre de dominio y crea las credenciales del usuario del sitio.
4. Cuando el sitio esté creado, edítalo y cambia el Root Directory para que apunte al directorio dist:

htdocs/www.yourdomain.com/dist

Astro genera su build de producción en dist/ por defecto (outDir: './dist'). CloudPanel tiene que servir desde ese directorio, no desde la raíz del proyecto.

CloudPanel también crea la redirección www↔non-www y fuerza HTTP→HTTPS por ti. No necesitas escribir esas reglas a mano.

Paso 2: Apunta el DNS a tu VPS

Añade un registro A en tu proveedor de DNS apuntando tu dominio a la dirección IP del VPS. Si usas Cloudflare, añade el registro A allí y activa el proxy para las ventajas del CDN y la protección DDoS.

dig +short www.yourdomain.com
# With Cloudflare proxy on, you'll see Cloudflare IPs (that's expected)
# With proxy off (DNS only), you should see your VPS IP

Paso 3: Genera un certificado SSL de Let’s Encrypt

En CloudPanel, ve a la sección SSL/TLS de tu sitio y haz clic en New Let’s Encrypt Certificate. CloudPanel gestiona la generación del certificado y la configuración de Nginx automáticamente.

Verifícalo antes de seguir:

curl -I https://www.yourdomain.com
# Expect: HTTP/2 200 (the CloudPanel placeholder page is fine at this stage)

curl -I http://www.yourdomain.com
# Expect: 301 redirect to https://www.yourdomain.com

Si curl te da un aviso de certificado, el certificado no se emitió. Comprueba que el registro DNS del Paso 2 ya resuelve antes de reintentar.

Paso 4: Instala Node.js 24 LTS con NVM

Astro necesita Node.js para compilar el sitio. CloudPanel crea usuarios de Linux aislados por sitio, así que instala Node.js bajo el usuario del sitio, no como root. Entra por SSH a tu VPS y cambia al usuario del sitio:

ssh root@your-server-ip
sudo su - www.yourdomain.com

Instala NVM (Node Version Manager). La v0.40.8 es la versión actual a septiembre de 2026:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | bash
source ~/.bashrc

Instala Node.js 24, la línea LTS activa:

nvm install 24
nvm alias default 24

Verifica la instalación:

node -v
# Should output v24.x.x

nvm ls
# Should show v24.x.x as default

Paso 5: Clona y configura tu proyecto Astro

Elimina los archivos de ejemplo que CloudPanel crea por defecto y coloca tu proyecto. El nombre del directorio debe coincidir con lo que CloudPanel espera (www.yourdomain.com).

cd htdocs
rm -rf www.yourdomain.com
git clone [email protected]:your-username/your-astro-repo.git www.yourdomain.com
cd www.yourdomain.com
npm install

ssh-keygen -t ed25519 -C "deploy-www.yourdomain.com"
cat ~/.ssh/id_ed25519.pub
# Copy the output, then in GitHub: repo Settings > Deploy keys > Add deploy key
# Paste it and leave "Allow write access" unchecked

cd htdocs
rm -rf www.yourdomain.com
npm create astro@latest www.yourdomain.com
cd www.yourdomain.com
npm install

Paso 6: Compila el sitio estático de Astro

Cuando tu sitio esté configurado y el contenido en su lugar, compila la versión de producción:

npm run build

Esto genera los archivos estáticos en dist/. Como el root directory de CloudPanel ya apunta a dist/, el sitio entra en producción en el momento en que termina el build.

Verifica:

curl -I https://www.yourdomain.com
# Expect: HTTP/2 200 and content-type: text/html

curl -I https://www.yourdomain.com/_astro/*.css
# Expect: 200. Astro emits hashed assets under /_astro/

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Paso 7: Automatiza rebuilds y despliegues

Hacer pull y build a mano cansa al tercer push de contenido. Todo el pipeline es pequeño:

Escribe un script de deploy mínimo como usuario del sitio, en ~/deploy.sh:

#!/usr/bin/env bash
set -euo pipefail

cd ~/htdocs/www.yourdomain.com
git pull
npm ci
npm run build

chmod +x ~/deploy.sh

Usa npm ci en lugar de npm install. Instala exactamente lo que hay en package-lock.json, así que un rebuild mañana se comporta como el rebuild de hoy. Ahora elige un disparador:

*/5 * * * * /home/www.yourdomain.com/deploy.sh >> /home/www.yourdomain.com/deploy.log 2>&1

cd ~/htdocs/www.yourdomain.com
git fetch -q
[ "$(git rev-parse HEAD)" = "$(git rev-parse @{u})" ] && exit 0

Uses el disparador que uses: la salida del build acaba en los logs de cron o en el journal del webhook. Cuando un deploy “silenciosamente” no ocurre, ese log es el primer sitio donde mirar. El script es también donde se engancha la salvaguarda de rollback (lo vemos a continuación).

Revertir un deploy fallido

npm run build vacía dist/ antes de escribir la salida nueva. Si el build falla a medias (error de markup, OOM kill, dependencia rota), puedes quedarte sirviendo nada. La solución es aburrida: guarda el build bueno anterior hasta que el nuevo esté probado.

Extiende el script de deploy con el intercambio:

#!/usr/bin/env bash
set -euo pipefail

cd ~/htdocs/www.yourdomain.com
git pull
npm ci

# Keep the previous build until the new one is proven
if [ -d dist ]; then
  rm -rf dist.last-known-good
  mv dist dist.last-known-good
fi

if npm run build && [ -f dist/index.html ]; then
  rm -rf dist.last-known-good
else
  echo "Build failed or produced no index.html, restoring previous dist" >&2
  if [ -d dist.last-known-good ]; then
    rm -rf dist
    mv dist.last-known-good dist
  fi
  exit 1
fi

La comprobación [ -f dist/index.html ] atrapa el peor caso: un build que sale con código 0 pero emite un árbol de salida vacío o incorrecto. Si falla, el backup vuelve a su sitio y Nginx sigue sirviendo la versión anterior.

Esto es una estrategia de “última salida estática buena conocida”, no despliegues versionados. Para un sitio estático en solitario es suficiente: el tiempo de restauración es un mv, y el único estado que importa (el repo git) está en otra parte.

Verifica el despliegue y configura las cabeceras de caché

Ejecuta este checklist tras el primer deploy y tras cada rebuild. Lleva 30 segundos y atrapa la mayoría de lo que se rompe:

Luego el caché. Astro emite archivos hasheados bajo /_astro/, así que esos se pueden cachear fuerte: Cache-Control: public, max-age=31536000, immutable. El HTML debe tener una vida corta; si no, los visitantes siguen viendo el deploy anterior tras un rebuild.

La plantilla de vhost estático de CloudPanel gestiona el serving básico, pero si quieres cabeceras explícitas y predecibles, añádelas en el editor Vhost del sitio (docs de vhost de CloudPanel):

location /_astro/ {
  add_header Cache-Control "public, max-age=31536000, immutable";
}

Deja el HTML con el manejo por defecto, o pon un Cache-Control corto (60 segundos es de sobra). En el lado de Cloudflare, pon Browser Cache TTL en “Respect Existing Headers” para que gane el origen. Así un rebuild se ve sin necesidad de purgar.

Cuando el sitio esté en vivo, vigílalo: monitoriza el uptime con Beszel y Uptime Kuma y sigue los recursos del servidor. Un sitio estático también puede caerse: expiración del certificado, disco lleno, mala configuración de Nginx en la próxima edición.

Si prefieres no poner Cloudflare delante, Bunny.net funciona como CDN edge drop-in sobre el mismo origen. Pull zone apuntando a tu VPS, la misma historia de caché inmutable de /_astro/.

Solución de fallos comunes

Alternativa: usa el tipo de sitio Node.js de CloudPanel

Para un sitio puramente estático, usa el tipo Static HTML site. Siempre puedes recrear el sitio como Node.js más adelante si pasas a SSR. Es un cambio de 10 minutos. Si aún estás decidiendo el panel en general, la comparativa de mejores paneles de servidor self-hosted cubre los trade-offs.

Conclusión

Desplegar Astro en un VPS con CloudPanel es el movimiento correcto cuando te quedas corto con los límites del hosting gratuito o quieres control sobre la máquina. El tipo de sitio Static HTML es su versión más simple: Nginx sirve dist/, ningún proceso Node corre en runtime, un VPS de 5 a 10 $/mes es suficiente, y los builds más rápidos de Astro 7 hacen que los rebuilds en esa máquina pequeña duelan menos. Añade el script de deploy, el intercambio de dist.last-known-good y el checklist de verificación, y tendrás una ruta de deploy en la que puedes confiar a la 1 de la madrugada.

Un repaso de seguridad: mantén CloudPanel actualizado. El panel corre con privilegios reales en tu servidor y el changelog muestra el historial de CVEs que demuestra que importa.

Si quieres un panel web que también funcione como reverse proxy para contenedores Docker, mira este curso:

Adónde ir después:

• Añade un formulario de contacto a tu sitio Astro (gratis, sin backend)
• Crea un blog Astro gratis en Cloudflare si quieres la ruta sin servidor
• Despliega Astro.js en Cloudflare Pages (hosting gratis, zero-config)
• Documentación de despliegue de Astro (cubre todas las plataformas soportadas)