VitePress Dokumentation auf Coolify deployen

Schritt-für-Schritt-Anleitung zum Deployen einer VitePress-Dokumentation auf Coolify.

Voraussetzungen

• Node.js 18+ installiert
• Git installiert
• Ein GitHub-Repository mit einem VitePress-Projekt
• Ein laufender Coolify-Server mit verbundenem GitHub-Account

1. VitePress-Projekt vorbereiten

Falls noch kein Projekt existiert:

mkdir meine-doku && cd meine-doku
npm init -y
npm install -D vitepress
npx vitepress init

Stelle sicher, dass die Build-Scripts in der package.json vorhanden sind:

{
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  }
}

2. Dockerfile erstellen

Erstelle eine Dockerfile im Projektroot:

FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run docs:build

FROM caddy:alpine
COPY --from=builder /app/docs/.vitepress/dist /usr/share/caddy

Was passiert hier:

1. node:18-alpine baut das VitePress-Projekt
2. npm ci installiert die Abhaengigkeiten
3. npm run docs:build erzeugt die statischen Dateien
4. caddy:alpine serviert die fertige Seite aus /usr/share/caddy

Angepasstes Output-Verzeichnis

Falls du outDir in deiner VitePress-Config geaendert hast, passe den COPY-Pfad im zweiten Stage entsprechend an. Beispiel: Bei outDir: '../dist' wird zu COPY --from=builder /app/dist /usr/share/caddy.

3. .dockerignore erstellen

Erstelle eine .dockerignore im Projektroot, um unnoetige Dateien vom Build auszuschliessen:

node_modules
dist
docs/.vitepress/dist
docs/.vitepress/cache
.git
.github

4. Lokal testen

Teste den Docker-Build lokal, bevor du auf Coolify deployst:

docker build -t meine-doku .
docker run -p 8080:80 meine-doku

Oeffne http://localhost:8080 im Browser. Die Dokumentation sollte vollstaendig geladen sein.

5. Auf GitHub pushen

git add -A
git commit -m "Add Dockerfile for Coolify deployment"
git push

6. In Coolify einrichten

1. Neues Projekt in Coolify anlegen (oder ein bestehendes waehlen)
2. Neue Ressource hinzufuegen > Application
3. GitHub als Source waehlen und dein Repository auswaehlen
4. Folgende Einstellungen konfigurieren:

Einstellung	Wert
Build Pack	Dockerfile
Port	80
Branch	main

5. Deploy klicken

Nach wenigen Minuten ist die Dokumentation unter der zugewiesenen Coolify-URL erreichbar.

7. Domain konfigurieren (optional)

In Coolify unter den Application-Einstellungen:

1. Eigene Domain hinzufuegen (z.B. docs.deine-domain.de)
2. SSL-Zertifikat wird automatisch ueber Let's Encrypt erstellt
3. DNS-Eintrag (A-Record oder CNAME) auf den Coolify-Server zeigen lassen

Auto-Deploy

Coolify deployed automatisch bei jedem Push auf den konfigurierten Branch, sofern Auto Deploy aktiviert ist. Aenderungen an der Dokumentation werden so ohne manuelles Eingreifen live gestellt.

Haeufige Fehler

Build schlaegt fehl mit "Cannot find module"

Stelle sicher, dass package-lock.json im Repository committed ist. Ohne diese Datei schlaegt npm ci fehl:

git add package-lock.json
git commit -m "Add package-lock.json"
git push

Seite zeigt 404

• Pruefe ob der outDir-Pfad in der VitePress-Config mit dem COPY-Pfad im Dockerfile uebereinstimmt
• Standard-Output ist docs/.vitepress/dist

Styles werden nicht geladen

• Pruefe ob base in der VitePress-Config korrekt gesetzt ist (nur noetig bei Subpfad-Deployment, z.B. base: '/docs/')