iac-blume

Blume als LXC auf Proxmox VE: baut ein Git-Repository mit Markdown/MDX zu einer statischen Dokumentations-Website und hält sie aktuell. Teil von iac.

Installation (auf der Proxmox-Node)

bash -c "$(curl -fsSL https://iac.heyer.systems/blume/ct.sh)"

Ohne Dialog: IAC_NONINTERACTIVE=1 und var_*-Variablen, z. B. var_blume_repo=https://git.example.org/team/docs.git – am einfachsten mit dem Generator auf https://iac.heyer.systems/apps/blume/. Nur als LXC, es gibt kein VM-Image.

Ressourcen: 2 CPU, 2 GiB RAM (ein Build braucht rund 1 GiB), 8 GiB Disk (Node.js und Blume belegen rund 1 GiB).

Das Repository

Einstellung	Bedeutung
blume_repo	URL des Repos: https://… oder SSH (git@host:team/docs.git). Leer = Platzhalterseite
blume_branch	Branch; leer = Standard-Branch des Repos

Das Repo ist ein Blume-Projekt: docs/ mit Markdown/MDX, darin mindestens docs/index.md oder docs/index.mdx (die Startseite), optional blume.config.ts im Wurzelverzeichnis (Titel, Theme, Navigation, deployment.site für Sitemap und Canonical-URLs). Ein Repo aus npx blume init passt so, wie es ist. Ein Code-Repo mit docs/-Ordner funktioniert auch.

Nicht unterstützt: eigene npm-Abhängigkeiten des Repos – dessen package.json wird ignoriert, Blume und seine Abhängigkeiten stellt iac. Ebenso keine Server-Funktionen von Blume (KI-Assistent, MCP-Server); die Seite ist rein statisch.

Repo oder Branch später ändern (im Gast):

nano /etc/iac/settings.env      # blume_repo=…, blume_branch=…
update

Private Repos: Jede Instanz hat einen eigenen SSH-Schlüssel. Den öffentlichen Teil als Deploy-Key (nur Lesen) im Repo eintragen und die SSH-URL verwenden:

cat /var/lib/blume/.ssh/id_ed25519.pub

Der Host-Key des Git-Servers wird beim ersten Verbinden übernommen (/var/lib/blume/.ssh/known_hosts).

Synchronisieren und Bauen

blume-sync.timer holt das Repo alle 5 Minuten (flacher Clone). Gebaut wird nur, wenn sich der Commit oder die Blume-Version geändert hat. Jeder Build landet in /var/lib/blume/www/releases/<commit>-blume-<version>, nginx liefert www/current aus – der Wechsel ist atomar, die letzten drei Builds bleiben liegen.

Schlägt ein Build fehl, bleibt die bisherige Seite online. Der Smoke-Test meldet dann „last sync succeeded“ als Fehler.

systemctl start blume-sync              # sofort synchronisieren und bauen
journalctl -u blume-sync -n 50          # Log des letzten Laufs
systemctl list-timers blume-sync.timer  # nächster Lauf
ln -sfn releases/<id> /var/lib/blume/www/current   # von Hand auf einen älteren Build zurück

Zugriff

• Web: http://<ip>/ (Port 80, nur aus privaten Netzen – davor gehört ein Reverse Proxy wie iac-traefik für TLS und einen öffentlichen Namen).
• Die Seite ist ohne Login lesbar. Für private Doku: eigene nginx-Regeln in /etc/blume/nginx.d/*.conf, z. B. auth_basic (Beispiel in /etc/blume/nginx.d/README).
• Neben den HTML-Seiten liefert Blume llms.txt, llms-full.txt und zu jeder Seite eine Markdown-Fassung (/<seite>.md) für KI-Werkzeuge.

Wo liegt was

Pfad	Inhalt
/etc/iac/settings.env	blume_repo, blume_branch
/etc/blume/blume.env	daraus erzeugt für blume-sync (gehört iac)
/etc/blume/nginx.d/	eigene nginx-Regeln (fasst iac nicht an)
/etc/nginx/sites-available/blume	nginx-Site (gehört iac)
/var/lib/blume/node_modules	Blume mit Abhängigkeiten
/var/lib/blume/src	Checkout des Repos
/var/lib/blume/www	gebaute Seiten, current = aktive
/usr/local/lib/blume/node	Node.js von nodejs.org

Update (im Gast)

update

• Blume: update installiert die neueste Version aus der npm-Registry (npm prüft jedes Paket gegen den Integritäts-Hash der Registry); danach wird die Seite mit der neuen Version neu gebaut.
• Node.js kommt von nodejs.org (geprüft gegen SHASUMS256.txt); Debian 13 hat nur Node.js 20, Blume braucht mindestens 22.19. Die Version ist in iac-blume festgelegt und ändert sich mit einer neuen Version von iac-blume.
• nginx und git kommen aus Debian und werden mit dem System aktualisiert.

Selbsttest (im Gast)

bash /var/lib/iac/src/core/bin/iac-smoke