pacod-demo

Ausprobieren

Die Demo läuft auf demo.pacod.io. Ihre Startseite zeigt jedes Produkt mit einer Beschreibung, einem Screenshot und den Links zu seiner Verwaltung und seinen Websites. Jedes Produkt hat seine eigene Subdomain:

Eine Anmeldung gilt für jedes Produkt: Wer sich bei einem anmeldet, ist bei allen angemeldet.

Warum es das gibt

Jedes pacod-Projekt läuft für sich allein, mit eigenen Kopien dessen, was es braucht: einer Datenbank, einem Edge, einer Anmeldung, einem Gateway. So probiert man eines aus. So sind sie aber nicht für das Zusammenspiel gedacht, und so sieht man nicht, was sie zusammen ergeben.

pacod-demo geht den umgekehrten Weg. Es bringt die fünf Produkte auf eine Maschine, als eine Plattform, mit je einer Instanz jeder gemeinsamen Komponente, und zeigt, was erst im Zusammenspiel sichtbar wird: eine Anmeldung, die jedes Produkt anerkennt, ein Gateway, über das jeder Modellaufruf läuft und das alle bepreist, und ein Satz Dashboards für den ganzen Stack.

Wie es aufgebaut ist

• Ein Netzwerk, eindeutige Namen. Alle fünf Repositorys folgen einer Konvention: Jeder Container tritt dem externen Docker-Netzwerk pacod-net bei, unter einem Namen, der über alle Repositorys eindeutig ist. Gemeinsame Komponenten heißen pacod-*; alles andere trägt das Präfix seines Besitzers (gw-, ap-, cms-, kb-).
• Die eigenen Compose-Dateien der Repositorys. Jedes Repository teilt sein Compose-Setup in eine App-Datei mit seinen eigenen Diensten und eine Standalone-Datei mit eigenen Kopien der gemeinsamen Komponenten, um es allein zu betreiben. Die Demo bindet die fünf App-Dateien unverändert ein. Ein kleines Overlay pro Repository entfernt nur veröffentlichte Ports, verweist Einstellungen auf die Dateien der Demo und setzt die öffentlichen Adressen.
• Von jeder gemeinsamen Komponente eine. Ein Caddy, ein PostgreSQL mit einer Datenbank und einer Eigentümerrolle pro Produkt, ein Qdrant, ein Embedding-Dienst, ein pacod-id, ein Gateway, eine Mail-Senke und ein Monitoring-Stack (Prometheus, Alertmanager, Grafana, der OpenTelemetry-Collector). Jede baut auf der Definition auf, die ein Repository bereits mitbringt, und übernimmt die Beiträge der Produkte aus deren platform/-Verzeichnissen: Caddy-Site-Blöcke, Datenbankskripte, Prometheus-Jobs, Regeln und Dashboards.
• Produkteigene Speicher bleiben beim Produkt. Das ClickHouse des Gateways, das MongoDB des CMS (eine Datenbank pro Website) und Gotenberg sowie Redis und pgbouncer der Agentenplattform.
• Der Bootstrap steuert die eigenen Skripte der Produkte: den Gateway- und Identitäts-Bootstrap von pacod-ap und den Provisioner von pacod-cms. Er erzeugt die Gateway-Schlüssel und Dienst-Tokens, mit denen die Produkte einander erreichen.

Konfiguration

Zwei Dateien. demo.env ist die Konfiguration und wird eingecheckt: Domain und Ports, das Zertifikat, die E-Mail des ersten Administrators, die Modelle jedes Produkts, das Embedding-Backend und die optionalen Komponenten. demo.local.env enthält die Geheimnisse der Maschine, das Passwort des Administrators und die Schlüssel der LLM-Anbieter; git ignoriert sie, und was sie setzt, gewinnt.

# demo.local.env
DEMO_ADMIN_PASSWORD=a-long-passphrase
ANTHROPIC_API_KEY=sk-...

LLM-Anbieter. Ohne Schlüssel geht jeder Modellaufruf an den Mock-Anbieter des Gateways: Die Demo läuft offline und make verify ist deterministisch, aber die Chat-Antworten sind vorgefertigt. Trag einen Schlüssel ein und führe make bootstrap aus, dann ist das Gateway mit dem echten Anbieter eingerichtet.

Das Embedding-Backend wird beim ersten make up festgelegt, weil die gespeicherten Vektoren davon abhängen. Die Voreinstellung auto nimmt das echte BGE-M3-Modell, wenn Docker genug Speicher dafür hat, und sonst einen leichten Ersatz.

Die optionale Komponente ingestion betreibt die Dokumentenaufnahme der Agentenplattform und lädt die Wissensbasis des Starter-Agenten. Sie ist ein großes Image und braucht 16 GB Speicher für Docker.

Auf einer Domain oder auf dem Laptop

Mit einem Zertifikat für die Domain und ihre Subdomains antwortet der Stack über HTTPS, und einfaches HTTP leitet nur weiter. Ist die Demo über die Maschine hinaus erreichbar, schließt sie, was nur auf einem Laptop sicher ist: Die Mail-Ansicht, Prometheus und Grafana fragen nach E-Mail und Passwort des Administrators, die Startseite nennt den Administrator nicht, und die Entwicklungs-Tokens der Agentenplattform sind aus.

Für eine Demo nur auf einer Maschine setzt du DEMO_DOMAIN=localhost und DEMO_HTTP_PORT=8800 und lässt das Zertifikat leer. Dann läuft alles über einfaches HTTP unter http://<name>.localhost:8800, was Browser ohne DNS auflösen.

Was es braucht

• Docker mit Compose 2.24 oder neuer, und make. Alles andere, von der Erzeugung der Geheimnisse bis zu den Prüfungen, läuft in Containern.
• Die fünf Projekt-Repositorys neben diesem ausgecheckt.
• Etwa 8 GB Speicher für Docker. Der ganze Stack mit dem echten Embedding-Modell braucht etwa 5 GiB, mit dem leichten Ersatz etwa 4 GiB.
• Etwa 30 GiB Plattenplatz für die Images. Das erste make up baut jedes Image aus dem Quellcode, zwei Rust-Workspaces, einen Maven-Build, mehrere Python-Images und zwei SvelteKit-Apps, und dauert 30 bis 60 Minuten. Spätere Starts dauern etwa zwei Minuten.

make down hält den Stack an und behält die Daten; make clean entfernt alles, was die Demo angelegt hat. Das README enthält alle Einstellungen und eine Tabelle zur Fehlerbehebung.