Déployer un projet Astro avec Dokploy et Nixpacks en optimisant la mise en cache pour accélérer les builds

1. Configuration de Dokploy

Dokploy est une plateforme de déploiement open source et auto-hébergée. Conçue comme une alternative gratuite à Heroku, Vercel et Netlify, elle repose sur Docker et Traefik.

1. Créez un nouveau projet et connectez votre dépôt GitHub

2. Définissez les variables d’environnement

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. Désactivez le nettoyage du cache

Service de projet → Clean Cache : désactivé
Serveur Web → Daily Docker Cleanup : désactivé

2. Moteur de build Nixpacks

Nixpacks, développé par Railway, est un outil open source qui transforme le code source en image Docker standard. Dokploy utilise Nixpacks comme moteur de build par défaut. Vous pouvez configurer le build via un fichier nixpacks.toml ou nixpacks.json.

Créez un fichier nixpacks.toml à la racine du projet, en spécifiant les répertoires de cache.

Priorité de configuration (faible → élevée) :

Logique par défaut du fournisseur
nixpacks.toml
Variables d’environnement
Paramètres CLI

Variables d’environnement courantes

Variable	Description
`NIXPACKS_INSTALL_CMD`	Commande personnalisée d’installation
`NIXPACKS_BUILD_CMD`	Commande personnalisée de build
`NIXPACKS_START_CMD`	Commande personnalisée de démarrage
`NIXPACKS_PKGS`	Paquets Nix supplémentaires à installer
`NIXPACKS_APT_PKGS`	Paquets Apt supplémentaires à installer
`NIXPACKS_INSTALL_CACHE_DIRS`	Répertoires de cache pendant l’installation
`NIXPACKS_BUILD_CACHE_DIRS`	Répertoires de cache pendant le build
`NIXPACKS_NO_CACHE`	Désactiver le cache (non recommandé)
`NIXPACKS_CONFIG_FILE`	Spécifier le fichier de configuration
`NIXPACKS_DEBIAN`	Utiliser une image de base Debian

3. Configuration du projet Astro

Astro est un framework moderne adapté aux sites riches en contenu tels que les blogs, pages marketing et e-commerce. Quand un site contient de nombreuses ressources statiques, les builds peuvent être ralentis. L’utilisation du cache permet d’accélérer considérablement les temps de build.

1. Définir le répertoire pour les fichiers en cache

Dans le fichier de configuration astro.config.mjs, spécifiez le répertoire de cache. Ce chemin peut être absolu ou relatif.

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

2. Fichier de configuration du cache Nixpacks

Créez un fichier nixpacks.toml à la racine du projet Astro avec les répertoires de cache et les commandes de build.

# Utiliser une version spécifique de Node.js et pnpm
[phases.setup]
nixPkgs = ["nodejs_22", "pnpm"]

# Installer les dépendances avec le cache pnpm
[phases.install]
cmds = ["pnpm install --frozen-lockfile"]
cacheDirectories = ["/root/.local/share/pnpm/store/v3"]

# Construire le projet et mettre en cache node_modules/.cache et astro_cache
[phases.build]
cmds = ["pnpm run build"]
cacheDirectories = [
  "node_modules/.cache",
  "astro_cache"
]

# Commande de démarrage (placeholder, via NGINX sur le répertoire dist)
[start]
cmd = "echo 'Build terminé. Servez le répertoire dist avec NGINX.'"

4. Optimiser le contexte de build Docker

Ajoutez un fichier .dockerignore à la racine du projet Astro :

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

5. Déploiement et vérification

Après déploiement sur Dokploy, vérifiez dans les logs de build que les lignes suivantes apparaissent, ce qui signifie que la mise en cache fonctionne :

1. Commande de build avec montage de cache

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. Réutilisation du cache par Astro (notamment pour les images optimisées)

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

✅ Si vous voyez les mentions --mount=type=cache et reused cache entry, cela signifie que le cache est activé et le temps de build optimisé.

🎉 Depuis l’onglet Deployments de Dokploy, vous pouvez constater que le temps de build passe de 31 minutes à seulement 3 minutes grâce au cache — un gain considérable en bande passante et en rapidité.

6. Remarques

Gardez les valeurs cacheDir (Astro) et cacheDirectories (Nixpacks) cohérentes
Chaque phase de build doit définir explicitement ses répertoires de cache
nixpacks.toml prend en charge "..." pour fusionner avec les variables d’environnement
Par défaut, node_modules/.astro n’est pas mis en cache — spécifiez-le manuellement dans astro_cache