Desplegar proyectos Astro con Dokploy y Nixpacks optimizando la caché para acelerar la compilación

1. Configuración de Dokploy

Dokploy es una plataforma de despliegue open source y autoalojada. Está diseñada como una alternativa gratuita a Heroku, Vercel y Netlify, construida sobre Docker y Traefik.

1. Crear un nuevo proyecto y conectar el repositorio de GitHub

2. Configurar variables de entorno

NIXPACKS_NODE_VERSION=22
NIXPACKS_PNPM_STORE_PATH=/root/.local/share/pnpm/store/v3
NIXPACKS_INSTALL_CACHE_DIRS=/app/node_modules
NIXPACKS_BUILD_CACHE_DIRS=/app/node_modules/.cache,/app/astro_cache

3. Desactivar limpieza de caché

Servicio del proyecto → Clean Cache: desactivado
Servidor Web → Daily Docker Cleanup: desactivado

2. Motor de compilación Nixpacks

Nixpacks, desarrollado por Railway, es una herramienta open source que convierte el código fuente en imágenes Docker estándar. Dokploy lo utiliza como motor de compilación predeterminado y permite configuraciones a través de un archivo nixpacks.toml o nixpacks.json.

Crea el archivo nixpacks.toml en el directorio raíz del proyecto y define las rutas de caché necesarias.

Prioridad de configuración (menor → mayor):

Lógica predeterminada del proveedor
nixpacks.toml
Variables de entorno
Parámetros CLI

Variables de entorno comunes

Variable	Descripción
`NIXPACKS_INSTALL_CMD`	Comando de instalación personalizado
`NIXPACKS_BUILD_CMD`	Comando de compilación personalizado
`NIXPACKS_START_CMD`	Comando de inicio personalizado
`NIXPACKS_PKGS`	Paquetes Nix adicionales
`NIXPACKS_APT_PKGS`	Paquetes Apt adicionales
`NIXPACKS_INSTALL_CACHE_DIRS`	Directorios de caché durante la instalación
`NIXPACKS_BUILD_CACHE_DIRS`	Directorios de caché durante la compilación
`NIXPACKS_NO_CACHE`	Desactiva caché (no recomendado)
`NIXPACKS_CONFIG_FILE`	Archivo de configuración personalizado
`NIXPACKS_DEBIAN`	Usar imagen base Debian

3. Configuración del proyecto Astro

Astro es un framework moderno ideal para sitios ricos en contenido como blogs, páginas de marketing y comercio electrónico. Cuando hay muchos recursos estáticos, el tiempo de compilación puede ser largo. Habilitar caché mejora considerablemente la eficiencia.

1. Establecer el directorio de caché de compilación

En el archivo astro.config.mjs, define el directorio donde se almacenará la caché de compilación. El valor puede ser una ruta absoluta o relativa.

// astro.config.mjs
export default defineConfig({
  cacheDir: './astro_cache',
});

2. Archivo de configuración de caché para Nixpacks

Crea el archivo nixpacks.toml en la raíz del proyecto Astro y configura los directorios de caché y los comandos de compilación.

# Usar versiones específicas de Node.js y pnpm
[phases.setup]
nixPkgs = ["nodejs_22", "pnpm"]

# Instalar dependencias y usar caché de pnpm
[phases.install]
cmds = ["pnpm install --frozen-lockfile"]
cacheDirectories = ["/root/.local/share/pnpm/store/v3"]

# Compilar el proyecto y almacenar caché de node_modules/.cache y astro_cache
[phases.build]
cmds = ["pnpm run build"]
cacheDirectories = [
  "node_modules/.cache",
  "astro_cache"
]

# Comando de inicio (placeholder, usando NGINX para servir `dist`)
[start]
cmd = "echo 'Compilación completada. Usa NGINX para servir el directorio dist.'"

4. Optimizar el contexto de compilación Docker

Agrega un archivo .dockerignore en la raíz del proyecto Astro:

node_modules
astro_cache
dist
*.log
.DS_Store
.vscode
.env*

5. Despliegue y verificación

Después del despliegue en Dokploy, revisa los registros de compilación para comprobar si se está utilizando la caché:

1. El comando de compilación monta directorios de caché

RUN --mount=type=cache,id=xxxx-node_modules/cache,target=/app/node_modules/.cache \
    --mount=type=cache,id=xxxx-astro_cache,target=/app/astro_cache \
    pnpm run build

2. Astro reutiliza entradas de caché (especialmente para imágenes)

▶ /_astro/202409272055577_Z2smeTW.avif (reused cache entry)
▶ /_astro/202409272055575_Z2wPyJN.avif (reused cache entry)
▶ /_astro/202409272055577_1IgP6g.avif (reused cache entry)

✅ Si ves --mount=type=cache y reused cache entry, significa que la caché está funcionando y se han acelerado los tiempos de compilación.

🎉 En la pestaña de despliegues de Dokploy, verás que el tiempo se reduce de 31 minutos a solo 3 minutos gracias a la caché—ahorrando tiempo y ancho de banda.

6. Notas

Mantén consistencia entre cacheDir (Astro) y cacheDirectories (Nixpacks)
Cada fase de compilación debe declarar sus cachés explícitamente
nixpacks.toml admite "..." para combinar con variables de entorno
Por defecto node_modules/.astro no se almacena en caché—debes indicarlo manualmente en astro_cache