Astro-Projekte mit Dokploy und Nixpacks bereitstellen und den Build mit Cache-Optimierung beschleunigen

1. Dokploy-Konfiguration

Dokploy ist eine Open-Source-Plattform zur Selbstbereitstellung. Sie wurde als kostenlose Alternative zu Heroku, Vercel und Netlify entwickelt und basiert auf Docker und Traefik.

1. Neues Projekt erstellen und GitHub-Repository verbinden

2. Umgebungsvariablen festlegen

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. Automatische Cache-Bereinigung deaktivieren

• Projektservice → Clean Cache: deaktiviert
• Webserver → Daily Docker Cleanup: deaktiviert

---

2. Nixpacks-Build-Engine

Nixpacks ist ein Open-Source-Build-Tool von Railway, das Quellcode in standardisierte Docker-Images umwandelt. Dokploy verwendet Nixpacks standardmäßig als Build-Engine. Die Konfiguration erfolgt über nixpacks.toml oder nixpacks.json.

Erstellen Sie im Projektstamm die Datei nixpacks.toml und definieren Sie dort die relevanten Cache-Verzeichnisse.

Priorität der Konfiguration (niedrig → hoch)

1. Standardlogik des Providers
2. nixpacks.toml
3. Umgebungsvariablen
4. CLI-Parameter

Gängige Umgebungsvariablen

Variable	Beschreibung
NIXPACKS_INSTALL_CMD	Benutzerdefinierter Installationsbefehl
NIXPACKS_BUILD_CMD	Benutzerdefinierter Build-Befehl
NIXPACKS_START_CMD	Benutzerdefinierter Startbefehl
NIXPACKS_PKGS	Zusätzliche Nix-Pakete installieren
NIXPACKS_APT_PKGS	Zusätzliche Apt-Pakete installieren
NIXPACKS_INSTALL_CACHE_DIRS	Cache-Verzeichnisse für Installation
NIXPACKS_BUILD_CACHE_DIRS	Cache-Verzeichnisse für Build
NIXPACKS_NO_CACHE	Caching deaktivieren (nicht empfohlen)
NIXPACKS_CONFIG_FILE	Konfigurationsdatei angeben
NIXPACKS_DEBIAN	Debian-Basis-Image verwenden

---

3. Astro-Projektkonfiguration

Astro ist ein modernes Web-Framework für contentlastige Seiten wie Blogs, Marketingseiten oder E-Commerce. Große Mengen statischer Ressourcen können Builds verlangsamen – mit aktiviertem Cache lässt sich dies deutlich optimieren.

1. Cache-Verzeichnis für Build-Outputs definieren

Legen Sie das Cache-Verzeichnis in der Datei astro.config.mjs fest. Relativer oder absoluter Pfad möglich.

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

---

2. Nixpacks-Caching-Konfiguration

Erstellen Sie die Datei nixpacks.toml im Projektstamm und definieren Sie Cache-Verzeichnisse und Build-Befehle.

# Node.js- und pnpm-Versionen definieren
[phases.setup]
nixPkgs = ["nodejs_22", "pnpm"]

# Abhängigkeiten mit pnpm-Cache installieren
[phases.install]
cmds = ["pnpm install --frozen-lockfile"]
cacheDirectories = ["/root/.local/share/pnpm/store/v3"]

# Projekt builden und Cache-Verzeichnisse angeben
[phases.build]
cmds = ["pnpm run build"]
cacheDirectories = [
  "node_modules/.cache",
  "astro_cache"
]

# Startbefehl (Platzhalter – dist-Verzeichnis wird per NGINX ausgeliefert)
[start]
cmd = "echo 'Build abgeschlossen. Bitte dist-Verzeichnis per NGINX bereitstellen.'"

---

4. Docker-Build-Kontext optimieren

Fügen Sie im Projektstamm eine .dockerignore-Datei hinzu:

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

---

5. Deployment & Überprüfung

Nach dem automatischen Deployment auf Dokploy überprüfen Sie die Build-Logs, ob Caching aktiv ist:

1. Build-Befehl verwendet gemountete Cache-Verzeichnisse

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 nutzt wiederverwendete Cache-Einträge (z. B. für Bildoptimierung)

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

✅ Wenn Sie --mount=type=cache und reused cache entry sehen, funktioniert das Caching und der Build wurde beschleunigt.

🎉 Im Deployments-Tab von Dokploy sehen Sie, dass sich die Build-Zeit von 31 Minuten auf 3 Minuten reduziert – mit Cache ein klarer Vorteil bei Zeit und Bandbreite.

---

6. Hinweise

• Achten Sie auf Konsistenz zwischen cacheDir (Astro) und cacheDirectories (Nixpacks)
• Definieren Sie die Cache-Verzeichnisse explizit in jeder Phase
• nixpacks.toml unterstützt "..." zur Kombination mit Umgebungsvariablen
• node_modules/.astro wird standardmäßig nicht gecached – manuell zu astro_cache hinzufügen