
Contenido · 14 secciones
- 01Qué vas a necesitar
- 02Cómo encaja todo
- 03Paso 1: prepara Astro para correr en un servidor
- 04Paso 2: envuelve el servidor (opcional, pero lo recomiendo)
- 05Paso 3: escribe un Dockerfile por etapas
- 06Paso 4: prueba en tu computador
- 07Paso 5: instala Dokploy en el VPS
- 08Paso 6: crea la aplicación
- 09Paso 7: conecta el dominio con HTTPS
- 10Paso 8: despliega y deja el despliegue automático
- 11Resultado esperado
- 12Mantenerlo
- 13Errores comunes
- 14Fuentes
Este blog no está en un hosting compartido. Corre en un servidor propio, dentro de un contenedor de Docker, y se publica solo cada vez que subo un cambio a GitHub.
Cuando escribí sobre WordPress o una web propia conté por qué lo prefiero. Aquí va el cómo, con los mismos archivos que usa este sitio.
Qué vas a necesitar
- Un proyecto de Astro en un repositorio de GitHub.
- Un VPS (servidor privado virtual). Dokploy pide al menos 2 GB de RAM y 30 GB de disco, con Ubuntu, Debian, Fedora o CentOS (Dokploy, instalación). Yo uso un VPS de Hostinger; es un enlace de afiliado: con él tienes 20 % de descuento y yo recibo una comisión.
- Un dominio que puedas apuntar al servidor.
- Manejarte en la terminal y saber leer un Dockerfile.
Cómo encaja todo
| Pieza | Qué hace |
|---|---|
| Astro | Genera las páginas como HTML al compilar. Los endpoints, como el del formulario, corren en un servidor de Node |
| Docker | Empaqueta el sitio y su servidor con una versión exacta de Node |
| Dokploy | Vive en el VPS: descarga el repositorio, construye la imagen, la publica y le pone el dominio con HTTPS |
| GitHub | Cada push a main le avisa a Dokploy que hay algo nuevo |
El recorrido de un cambio es corto: escribo, hago git push, Dokploy construye la imagen nueva y reemplaza la anterior.
Paso 1: prepara Astro para correr en un servidor
Si tu sitio es solo HTML estático, puedes saltarte el servidor de Node. Este blog tiene endpoints (el formulario de contacto), así que usa el adaptador de Node en modo standalone (Astro, adaptador de Node):
// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
export default defineConfig({
site: process.env.PUBLIC_SITE_URL || 'https://miguelurra.lat',
// Todo es estático por defecto; solo los endpoints de /api corren en el servidor.
output: 'static',
adapter: node({ mode: 'standalone' })
});
Con output: 'static', cada página se genera al compilar y el servidor solo ejecuta código para los endpoints que lo piden.
Paso 2: envuelve el servidor (opcional, pero lo recomiendo)
El adaptador de Node trae su propio servidor. Yo lo envuelvo en un archivo server.mjs para tres cosas: agregar cabeceras de seguridad a todas las respuestas, comprimir con Brotli o gzip, y responder en /healthz para que Docker sepa si el sitio está vivo.
// server.mjs (resumido)
import http from 'node:http';
import compression from 'compression';
process.env.ASTRO_NODE_AUTOSTART = 'disabled';
const { handler } = await import('./dist/server/entry.mjs');
const compress = compression({ threshold: 1024 });
http.createServer((req, res) => {
if (req.url === '/healthz') {
res.writeHead(200, { 'Content-Type': 'text/plain' });
return res.end('ok');
}
res.setHeader('X-Content-Type-Options', 'nosniff');
res.setHeader('X-Frame-Options', 'DENY');
compress(req, res, () => handler(req, res));
}).listen(Number(process.env.PORT) || 4321, process.env.HOST || '0.0.0.0');
El archivo real agrega una política de seguridad de contenido, caché por tipo de archivo y un cierre ordenado cuando Docker detiene el contenedor.
Paso 3: escribe un Dockerfile por etapas
Este es el Dockerfile del blog. Tiene cuatro etapas para que la imagen final lleve solo lo necesario:
FROM node:22.23.4-alpine AS base
WORKDIR /app
# 1. Dependencias completas, para compilar
FROM base AS deps
COPY package.json package-lock.json* ./
RUN npm ci
# 2. Compilación
FROM base AS build
ARG PUBLIC_SITE_URL=https://miguelurra.lat
ENV PUBLIC_SITE_URL=$PUBLIC_SITE_URL
COPY --from=deps /app/node_modules ./node_modules
COPY . .
ENV NODE_ENV=production
RUN npm run build
# 3. Solo dependencias de producción
FROM base AS prod-deps
COPY package.json package-lock.json* ./
RUN npm ci --omit=dev && npm cache clean --force
# 4. Imagen final, con un usuario sin privilegios
FROM node:22.23.4-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production HOST=0.0.0.0 PORT=4321
COPY --from=prod-deps --chown=node:node /app/node_modules ./node_modules
COPY --from=build --chown=node:node /app/dist ./dist
COPY --from=build --chown=node:node /app/package.json ./package.json
COPY --chown=node:node server.mjs ./server.mjs
USER node
EXPOSE 4321
HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
CMD wget -qO- http://127.0.0.1:4321/healthz || exit 1
CMD ["node", "server.mjs"]
Tres decisiones que importan:
- La versión de Node va fija (
22.23.4), no como22a secas. Así sé exactamente qué corre en producción, y un parche de seguridad entra cuando yo cambio ese número y reconstruyo. Lo aprendí en octubre, cuando salió un parche crítico de Node y el contenedor que estaba corriendo se había construido antes. PUBLIC_SITE_URLentra como argumento de compilación, no solo como variable del contenedor. Astro la usa al compilar para el sitemap y las URL canónicas.- El contenedor corre con el usuario
node, no con el administrador.
Agrega también un .dockerignore con node_modules, .git, dist y .env, para que nada de eso entre a la imagen.
Paso 4: prueba en tu computador
Antes de tocar el servidor, confirma que la imagen funciona:
docker build -t mi-blog .
docker run --rm -p 4321:4321 mi-blog
Abre http://localhost:4321 y http://localhost:4321/healthz. Si la segunda responde ok, la imagen está bien.
Paso 5: instala Dokploy en el VPS
Entra al servidor por SSH y ejecuta el instalador oficial (Dokploy, instalación):
curl -sSL https://dokploy.com/install.sh | sh
Necesita libres los puertos 80 y 443 (los usa Traefik, que enruta el tráfico) y el 3000 (el panel). Si alguno está ocupado, la instalación falla. Al terminar, entra a http://IP-DE-TU-SERVIDOR:3000 y crea la cuenta de administrador.
Paso 6: crea la aplicación
En el panel, crea un proyecto y dentro una aplicación:
- En la pestaña General, conecta GitHub, elige el repositorio y la rama
main. - En Build Type, elige Dockerfile. En “Dockerfile Path” va
Dockerfiley en “Docker Context Path”,.(Dokploy, tipos de compilación). - En la pestaña Environment, carga las variables del contenedor (en mi caso, las del correo del formulario).
- En el mismo lugar, en Build Time Arguments, agrega
PUBLIC_SITE_URL=https://tu-dominio.com. Es la que el Dockerfile recibe conARG.
Las claves van en Dokploy, nunca en el repositorio. En el repositorio solo queda un .env.example sin valores.
Paso 7: conecta el dominio con HTTPS
- En tu proveedor de dominio, apunta el dominio a la IP del servidor.
- En la pestaña Domains de la aplicación, agrega el dominio en Host.
- En Container Port, pon
4321, el mismo puerto que expone el Dockerfile. - Activa HTTPS y elige
letsencryptcomo certificado (Dokploy, dominios).
Paso 8: despliega y deja el despliegue automático
Presiona Deploy la primera vez. En la pestaña Deployments ves cómo avanza la compilación, y en Logs, lo que imprime el servidor.
Desde ahí, con GitHub como origen, cada push a main dispara un despliegue nuevo sin hacer nada más (Dokploy, despliegue automático).
Resultado esperado
https://tu-dominio.com/healthzrespondeok.- El sitio carga con HTTPS y sin advertencias del navegador.
- Un cambio subido a
mainaparece publicado unos minutos después, sin entrar al servidor.
Mantenerlo
Una web propia no se actualiza sola, y esa es la parte que hay que tomarse en serio:
- Corre
npm auditseguido y antes de cada despliegue. Si encuentra algo,npm audit fixsuele bastar. - Cuando sale un parche del lenguaje, cambia la versión fija en el Dockerfile y reconstruye, aunque no hayas tocado nada del contenido.
- Revisa los registros en la pestaña Logs si algo se comporta raro.
Errores comunes
- Poner otro puerto en Container Port. Si el Dockerfile expone
4321y el dominio apunta a otro, el sitio no responde. - Pasar
PUBLIC_SITE_URLsolo como variable del contenedor. Astro la necesita al compilar; si llega tarde, el sitemap y las canónicas quedan con la URL por defecto. - Una rama distinta en Dokploy y en GitHub. Si haces push a una rama que no es la configurada, no se despliega nada.
- Asustarse con un error de un par de minutos. Mi dominio pasa por Cloudflare, y una vez, justo después de publicar, la web respondió con errores 522 y 525 mientras el contenedor nuevo arrancaba. A los pocos minutos volvió sola. Si dura más, revisa la pestaña Logs.
Si te interesa el porqué de todo esto, está en WordPress o una web propia. Y si llegaste por la parte de buscadores, qué es llms.txt explica otro de los archivos que publica este sitio.
Fuentes
- Dokploy. Installation. Requisitos, puertos e instalador.
- Dokploy. Build Type. Tipos de compilación y argumentos de compilación.
- Dokploy. Domains. Dominios, HTTPS y certificados.
- Dokploy. Auto Deploy. Despliegue automático desde GitHub.
- Astro. @astrojs/node. Adaptador de Node y modo standalone.
- #Astro
- #Docker
- #Dokploy
- #VPS
- #Desarrollo web
¿Te pasó algo parecido o no estás de acuerdo? Escríbeme.