Installationsübersicht
PlantPulse AI läuft als ein einziger docker compose-Stack. Das Original ist
compose/docker-compose.yml, und auch sämtliche Betriebsskripte handhaben die Container ausschließlich über diese Datei.
curl -fsSL https://product.kopens.io/plantpulse-ai/install.sh | sudo bash
Näheres finden Sie unter Einzeilige Installation. Diese Seite beschreibt, was wo installiert wird und was das Installationsskript tatsächlich tut.
Wo wird installiert
/opt/kopens/
├── plantpulse-ai-docker/ ← 설치 본체 (bin · compose)
├── plantpulse-ai-inference-server/ ← 형제 저장소
└── plantpulse-timeseries-insight-server/ ← 형제 저장소
compose/docker-compose.yml bindet die Dateien der beiden Repositories per relativem Pfad per Bind-Mount ein (z. B. die Gateway-
Konfiguration litellm-config.yaml). Ohne sie startet der Stack nicht — selbst bei START=1 verweigert das Installationsprogramm
den Start und gibt den Namen des fehlenden Repositories aus. Die einzeilige Installation und das Air-Gap-Bundle
laden alle drei zusammen herunter, sodass Sie sich darum nicht kümmern müssen. Wenn Sie jedoch manuell
git clone durchführen, müssen Sie alle drei als Schwester-Verzeichnisse anlegen.
| Was | Wo |
|---|---|
| Installationskörper | /opt/kopens/plantpulse-ai-docker |
| Konfigurations-/Zugangsdaten-Original | /etc/kopens/plantpulse-ai.env (0600) |
| Die zugehörige Original-Vorlage | <설치 본체>/compose/env.gb10.example (AWS g7e: env.g7e.example) |
| Hardware-Profil | <설치 본체>/compose/profiles/gb10.env · g7e.env — GPU-Zuteilung. Wird durch PP_HW_PROFILE in der Host-Env ausgewählt |
| Docker-Speicherwurzel | /data1/docker-data (änderbar über DOCKER_DATA_DIR) |
Was wird gestartet — fünfundzwanzig Container
| Kategorie | Container | Aufgabe |
|---|---|---|
| Eingang | plantpulse-proxy | nginx (non-root). Nimmt 80 · 443 des Hosts sowie die HTTPS-Verwaltungskonsole (5960) entgegen und leitet sie nach innen weiter |
| Oberfläche | plantpulse-copilot-web · plantpulse-admin-web | Copilot-Oberfläche · Verwaltungskonsole (HTTP 5959) |
| Inferenz | plantpulse-llm · plantpulse-emb · plantpulse-rerank | vLLM — Generierung · Embedding · Re-Ranking |
| Gateway | plantpulse-litellm (4000) | Bündelt alle Modellaufrufe an einem Ort |
| Dokumente | plantpulse-rag-api · plantpulse-lightrag · plantpulse-docling-serve · plantpulse-document-understanding-api | Liest · zerlegt · durchsucht Dokumente |
| Wissen | plantpulse-neo4j (7474 · 7687) · plantpulse-qdrant | Wissensgraph · Vektorindex |
| Digital Thread | plantpulse-digital-thread-api (7140, nicht am Host geöffnet) · plantpulse-digital-thread-neo4j | Spiegel des Anlagengraphen und Connector-Registry · dessen dediziertes Neo4j (nicht am Host geöffnet) |
| Zeitreihe | plantpulse-timeseries-insight-api (8970) · plantpulse-timeseries-insight-server (8980, nicht am Host geöffnet) | Anomalieerkennung · Prognose |
| Vision | plantpulse-vision-api | Bildverständnis |
| Verwaltung | plantpulse-admin-api | Backend der Verwaltungskonsole |
| Beobachtung | plantpulse-phoenix (6006, nicht am Host geöffnet) · plantpulse-dcgm | Trace-UI · GPU-Metriken |
| Transkription | plantpulse-asr · plantpulse-asr-audio | Sprache → Text (vLLM Whisper) · Einmal-Dienst, der die Audio-Bibliothek ins Volume überträgt und sich dann beendet. Läuft nur bei Installationen mit aktiviertem Video/Audio (PI_MEDIA_ENABLED=true) → Video-/Audio-Erfassung |
| Registry | plantpulse-registry · plantpulse-registry-ui | Interner Image-Speicher für Air-Gap-Netzwerk — läuft beim Standardstart nicht |
Im Standardstart laufen einundzwanzig Container (ohne die beiden Transkriptions- und die beiden Registry-Container).
Mit aktiviertem Video/Audio kommen zwei Transkriptions-Container hinzu, macht dreiundzwanzig
(plantpulse-asr-audio endet normalerweise nach getaner Arbeit mit «Exited (0)»). Die beiden Digital-Thread-Container wurden im Oktober 2026 neu eingeführt.
8970 und 7115 sind die Stellen, an denen MCP-Clients direkt andocken (z. B. Platform-CEP-Anomalieerkennung, Claude Desktop). Alle anderen liegen hinter dem Proxy.
Was install.sh tut
Die einzeilige Installation bedeutet, dass bootstrap.sh das Repository herunterlädt und dieses Skript ausführt.
Nach Erkennung des Betriebssystems (RHEL-Familie / Debian-Familie) werden die Schritte in der im Log
ausgegebenen Reihenfolge abgearbeitet.
| Schritt | Aufgabe | Host-global |
|---|---|---|
| 1 | Locale (ko_KR.UTF-8) · Zeitzone — der PP_TZ-Wert wird einheitlich festgelegt, sodass auch das Host-Betriebssystem auf diese Zeitzone eingestellt wird (bei Installation übergebener Wert → bereits in Env vorhandener Wert → Host-Zeitzone (falls nicht UTC) → Asia/Seoul) | ✅ |
| 2 | Swap deaktivieren (wird auch in /etc/fstab berücksichtigt) | ✅ |
| 3 | Installation von Docker CE + buildx + compose-v2-Plugin — wird übersprungen, falls bereits vorhanden | |
| 3b | Installation von NVIDIA-Treiber + Container-Toolkit, Registrierung der nvidia-Runtime in Docker (wird bei SKIP_GPU=1 übersprungen) | |
| 4 | /etc/docker/daemon.json und Datenverzeichnisse (siehe unten) | |
| 5 | OS-Tuning — chrony · limits · sysctl · tmpfiles | ✅ |
| 6 | Öffnen der Firewall — es werden nur die von compose tatsächlich veröffentlichten Ports geöffnet (SSH 22 wird vorab geöffnet). Ports, die bereits von einem Prozess außerhalb dieses Stacks belegt sind, werden als Warnung ausgegeben, inklusive Hinweis auf verschiebbare Schlüssel | ✅ |
| 7 | Prüfung der Anmeldung bei der internen Registry (wird bei SKIP_LOGIN=1 übersprungen) | |
| 8 | Vorbereitung des Konfigurations-Sidecars — die Vorlage wird nach /etc/kopens/plantpulse-ai.env kopiert und die Werte befüllt → nur bei START=1 erfolgt der Modellempfang · Image-Pull · Start |
Schritte mit der Markierung «Host-global» ändern nicht dieses Produkt selbst, sondern die
Konfiguration des gesamten Hosts. HOST_TUNING behandelt diese vier Schritte (Tabelle unten).
Wird HOST_TUNING nicht übergeben, laufen aber Container außerhalb dieses Compose-Projekts, ist der
Standardwert plan — es werden nur die geplanten Änderungen ausgegeben, ohne etwas zu schreiben. Wenn Sie die Ausgabe
geprüft haben und die Anwendung wünschen, führen Sie den Vorgang erneut mit HOST_TUNING=apply aus. Auf dedizierten
Maschinen (keine anderen Container) ist der Standard apply.
Vorhandene höhere sysctl-Werte am Host werden nicht abgesenkt.
Schritt 4 — bereits vorhandenes Docker bleibt unangetastet
| Docker auf diesem Host | Verhalten |
|---|---|
| Wurde in diesem Lauf neu installiert | daemon.json wird mit Standardwerten (overlay2, DOCKER_DATA_DIR=/data1/docker-data) geschrieben |
| War bereits vorhanden | Speicher (data-root · storage-driver) gilt im docker info des laufenden Daemons als Original und wird nicht neu geschrieben. Geplante Änderungen werden nur ausgegeben, es erfolgt kein Neustart |
Um Änderungen an einem bereits vorhandenen Docker inklusive Neustart zuzulassen, übergeben Sie ALLOW_DOCKER_RECONFIGURE=1.
Dies ist auch nötig, wenn Sie ein anderes DOCKER_DATA_DIR verwenden möchten.
Früher wurden fehlende Schlüssel in einer vorhandenen daemon.json mit Standardwerten aufgefüllt, wodurch
Container und Images auf Hosts mit abweichender Speicherwurzel unsichtbar wurden. Deshalb ist der Standard
jetzt «unangetastet lassen». Verwenden Sie ALLOW_DOCKER_RECONFIGURE=1 nur, wenn Sie diese Konsequenz verstehen.
Wird START=1 nicht übergeben, werden die Konfigurationsdateien erstellt und der Vorgang angehalten. Dies ist
der Standard für Betreiber, die die Werte prüfen und den Stack manuell starten möchten.
Häufig verwendete Umgebungsvariablen
| Variable | Bedeutung |
|---|---|
START=1 | Geht über die Vorbereitung von .env hinaus bis zum Start — hilft auch beim automatischen Modellempfang und der Installationsprüfung |
INTERACTIVE=1 | Fragt leere Werte ab (Standard ist nicht-interaktiv) |
ENV_TEMPLATE | Original-Vorlage des Sidecars. Standard env.gb10.example (GB10 · arm64), AWS g7e: env.g7e.example (amd64). Wird nicht automatisch ausgewählt |
ENV_TEMPLATE_SKIP_ARCH_CHECK=1 | Stoppt das Installationsprogramm, falls Vorlage und Architektur dieser Maschine nicht übereinstimmen. Überspringen Sie diese Prüfung nur bewusst, z. B. beim Testen neuer Hardware |
HOST_TUNING | skip · plan · apply — Host-globale Konfiguration (Locale · Zeitzone · Swap · chrony · limits · sysctl · tmpfiles · Firewall) sowie Paketinstallation (Docker CE · NVIDIA-Treiber/Toolkit · jq). Bei skip · plan werden weder Pakete installiert noch die nvidia-Runtime registriert (kein Docker-Neustart) — es wird nur ausgegeben, was zu tun wäre, und der Vorgang hält an Schritten an, die ohne dies nicht funktionieren. Standard ist apply, bei Hosts mit laufenden anderen Containern plan |
DOCKER_DATA_DIR | Speicherwurzel des in diesem Lauf neu installierten Dockers (Standard /data1/docker-data). Ein bereits vorhandenes Docker behält seine eigene Wurzel |
ALLOW_DOCKER_RECONFIGURE=1 | Erlaubt Änderung · Neustart der daemon.json eines bereits vorhandenen (laufenden) Dockers |
SKIP_GPU=1 | Überspringt Schritt 3b (Installation von NVIDIA-Treiber · Toolkit) — für Hosts, bei denen der Treiber separat vom Betriebsteam verwaltet wird |
SKIP_WAIT=1 | Überspringt das «Warten auf Antwort» nach START=1 sowie die Installationsprüfung |
WAIT_READY_MIN | Obergrenze (Minuten) für obige Wartezeit. Standard 15 |
SKIP_LOGIN=1 | Überspringt die Anmeldung bei der internen Registry — für Air-Gap-Netzwerk. Überspringt auch den Image-Pull |
SKIP_PULL=1 | Startet auf einer internetfähigen Maschine mit bereits heruntergeladenen Images |
INSECURE_REGISTRY | Fügt eine interne Kunden-Registry (HTTP) der daemon.json-Positivliste hinzu |
SKIP_PULL=1 kann zum Start mit «einem alten Build» führenDer Image-Tag ist YYYY.MM und wird unter demselben Namen aktualisiert. Ein lokal zwischengespeicherter Tag mit
demselben Namen kann vom Vormonat stammen. Verwenden Sie diese Option nicht, wenn Sie die Version
unbedingt genau treffen müssen.
Was wird abgefragt und was «erzeugt» das Installationsprogramm
Das Installationsprogramm fragt Werte ab, die nur Menschen oder die Plattform kennen, und erzeugt selbst Geheimnisse, die ausschließlich innerhalb des Stacks genutzt werden.
| Werte | |
|---|---|
| Abgefragt | TLS-Zertifikat-SAN (PP_PROXY_CERT_SAN) · Adresse und Schlüssel zum Empfang der Plattform-Zugangsdaten (PP_DATALAKE_ADMIN_URL · PP_DATALAKE_ADMIN_API_KEY) — danach, einzeln, die verbleibenden Platzhalter (Plattform-API-Token · Admin-Passwort · Neo4j-Passwort usw.) |
| Erzeugt | Gateway-Masterschlüssel · Salt · Inferenzserver-Schlüssel · Inbound-Schlüssel · RAG-Schlüssel · Verwaltungssitzungs-Geheimnis · zwei Verschlüsselungsschlüssel für gespeicherte Zugangsdaten (PI_COPILOT_SECRET_KEY · PI_DT_SECRET_KEY) |
Abgefragt wird nur bei INTERACTIVE=1. Alle abgefragten Werte können auch über gleichnamige Umgebungsvariablen
übergeben werden — bei Angabe im Stil von PP_DATALAKE_ADMIN_URL=… PP_DATALAKE_ADMIN_API_KEY=… PP_API_TOKEN=… PI_ADMIN_PASSWORD=… bash befüllt das Installationsprogramm
ausschließlich noch als Platzhalter verbliebene Schlüssel mit diesem Wert (Neuveröffentlichung 2026.10 —
früher wurden nur die beiden Werte TLS-SAN und Plattform-Zugangsdaten entgegengenommen). Was danach noch fehlt,
füllen Sie interaktiv aus oder bearbeiten /etc/kopens/plantpulse-ai.env direkt. Auch erzeugte Werte werden
nur dann befüllt, wenn sie noch Platzhalter sind; bereits von Menschen eingetragene Werte werden nicht überschrieben.
Eine in der Env-Datei bereits vorhandene TLS-SAN bleibt auch bei Neuinstallation unverändert — zum Ändern
führen Sie den Vorgang mit explizitem PP_PROXY_CERT_SAN=… aus.
Plattform-Host (PP_HOST) sowie Konto · Passwort von Plattform-PG · Aster-TSDB · Redis werden nicht mehr abgefragt
und auch nicht mehr in die Env geschrieben. Der Plattform-Host wird aus dem Host von PP_DATALAKE_ADMIN_URL berechnet, und
Konto · Passwort werden von Containern und Host-Skripten beim Start von der Plattform bezogen. Wird diesem
Lauf dennoch ein Wert wie PP_PG_USER übergeben, erscheint lediglich eine Warnung, dass er nicht in die Env
geschrieben wird. Der Trust-Anchor root.crt wird vom Installationsprogramm nicht angelegt — bereiten Sie ihn selbst vor →
siehe unten „Plattform-Zugangsdaten beziehen — Vorbereitung vor dem Start“
Damit der Browser nicht blockiert, muss das selbstsignierte Zertifikat des Proxys die Adresse/den Namen enthalten, über den Menschen zugreifen. Das Installationsprogramm setzt standardmäßig die Adresse dieses Hosts, aber öffentliche IPs außerhalb von NAT, Load-Balancer-VIPs oder Domainnamen sind für diese Box nicht sichtbar. Bei interaktiver Installation wird dies unbedingt abgefragt, bei nicht-interaktiver wird nur die Host-Adresse gesetzt, mit anschließender Warnung. Für den Zugriff über externe Namen geben Sie mehrere, durch Komma getrennt, an.
curl -fsSL https://product.kopens.io/plantpulse-ai/install.sh \
| sudo PP_PROXY_CERT_SAN=ai.example.com,203.0.113.10 bash
Manuelle Eingabe führt zu kurzen, sich überschneidenden Werten — tatsächlich kam es vor, dass zwei Hosts denselben, in der Dokumentation als Beispiel angegebenen Schlüssel gemeinsam verwendeten. Jetzt erzeugt das Installationsprogramm die Schlüssel, der Betreiber muss sie nur noch rotieren.
Der vom Installationsprogramm erzeugte Inbound-Schlüssel (PI_INBOUND_API_KEY) ist der gemeinsame Eingangsschlüssel von
RAG · Zeitreihen-Insights · Dokumentenverständnis · Vision · Digital Thread. Ist er leer, startet die Vor-Start-Prüfung
(bin/lint-env.sh) den Stack nicht, und auch die einzelnen Dienste verweigern jeweils den Start — ein Start ohne Schlüssel
ist nur möglich, wenn absichtlich der Entwicklungsschalter PI_INBOUND_AUTH_DISABLED=true gesetzt wird. Wenn Sie die Env manuell erstellt
haben, füllen Sie diese Zeile unbedingt aus → Umgebungsvariablen konfigurieren
Was bei START=1 zusätzlich passiert — drei weitere Dinge
Seit 2026.09 „empfängt, befüllt und prüft“ der Startpfad die Werte.
| Schritt | Aufgabe |
|---|---|
| Platzhalterprüfung | 🔴 Stoppt, wenn noch CHANGE_ME_* oder <PLACEHOLDER> vorhanden sind. Früher wurde nur gewarnt und mit „Installation abgeschlossen“ beendet |
| Vorab-Prüfung der Plattform-Zugangsdaten | Vor dem Image-Pull wird einmal versucht, Zugangsdaten von der Plattform zu beziehen. Bei falschem Schlüssel oder fehlendem root.crt stoppt der Vorgang mit [FATAL] [platform-credentials] …, ohne irgendetwas zu starten. Auch bei leeren Werten wird gestoppt |
| Automatischer Modellempfang | Fehlende Modelle werden von model.kopens.ai bezogen, SHA256 geprüft und entpackt. Früher ein manueller Vorgang |
| Warten auf Antwort | Wartet bis zu WAIT_READY_MIN (15) Minuten, bis Verwaltungskonsole (:5959/health) und RAG-Gateway (:7115/ping) antworten. Bei Überschreitung endet die Installation als fehlgeschlagen. Es wird auch geprüft, ob die Konsolen-HTTPS (:5960) antwortet, fließt aber nicht in die Fehlerbewertung ein |
| Installationsprüfung | Prüft nicht nur, ob der Stack „läuft“, sondern ob er „funktioniert“ (siehe unten) |
Startet der Stack trotz verbliebener Platzhalter, sieht die Oberfläche einwandfrei aus, während die Funktionen
versagen. Deshalb verweigert START=1 den Start. Wenn Sie nur vorbereiten möchten, übergeben Sie einfach
START nicht (bei Air-Gap-Installationen werden die Werte ohnehin später eingetragen). Ab 2026.10 gilt dieselbe
Prüfung auch, wenn Sie den Stack später mit bin/up.sh starten — verbliebene Platzhalter werden mit ihrem Schlüsselnamen
ausgegeben, und der Start wird verweigert.
Bei einer Clean-Installation kam es vor, dass der Status durchweg running · HTTP 200 war, obwohl drei Dienste faktisch nicht funktionierten — alle drei bestehen den Container-Healthcheck.
- Da niemand ein Modell empfangen hat, startet der Inferenzserver ständig neu
- Der Gateway-Schlüssel ist leer, sodass sämtliche Chats 401 liefern
- Das Plattform-Token ist ein Platzhalter, sodass MCP-Tools stillschweigend 0 ergeben
Die Installationsprüfung (bin/verify-install.sh) betrachtet genau diese drei Punkte. Jede Prüfung antwortet mit OK · FAIL
· „nicht messbar“, und nicht Messbares zählt nicht als bestanden.
Vier Schritte zur Prüfung, ob die Installation «funktioniert»
bin/status.sh—21/21 running · HTTP=200(einundzwanzig im Standardstart)bin/verify-install.sh—OK 4 · FAIL 0. Schon ein einziges FAIL beendet die Installation als fehlgeschlagen- AI-Verwaltungskonsole › MCP Gateway › Servers — eingebaute Server wie Plattform · Zeitreihen-Insights · Digital Thread · Engineering-Berechnung müssen fehlerfrei sein und eine Werkzeuganzahl ungleich 0 haben. Bei 0 prüfen Sie das Plattform-Token → MCP-Werkzeugkarte
- Stellen Sie im Chat einmal eine Frage — es kam vor, dass 1–3 vollständig grün waren, der Chat aber dennoch nur 401 lieferte
- Beim ersten Start auf einem neuen Host kann ein zweimaliger Start nötig sein. Wird der Dokumentenparser innerhalb der Wartezeit auf Abhängigkeiten nicht gesund, stoppt der Vorgang dort. Ein erneuter Start führt zu 21/21.
- 🔴 Ein direktes Ausführen von
docker compose upsetzt ein bereits ausgeliefertes Image zurück. Deployments binden den Tag nur an diesen einen Aufruf und hinterlassen ihn nicht in.env(beabsichtigtes Verhalten). Verwenden Sie zum Hochfahren das bereitgestellte Skript.
Plattform-Zugangsdaten beziehen — Vorbereitung vor dem Start
Ab 2026.10 werden Konto · Passwort · Port von Plattform-PG · Aster-TSDB · Redis · RustFS beim Start der Container von der Plattform bezogen (Copilot · Zeitreihen-Insights-API · LightRAG · RAG-API · Digital Thread · LiteLLM). Compose übergibt diese Werte nicht — sind die folgenden vier Punkte nicht vorbereitet, stoppen die betroffenen Container mit FATAL.
| Vorzubereiten | Woher |
|---|---|
PP_DATALAKE_ADMIN_URL | https://<플랫폼 호스트>:4950 — dieser Host wird gleich zu PP_HOST |
PP_DATALAKE_ADMIN_API_KEY | gleichnamige Zeile in der /etc/kopens/plantpulse-platform.env des Plattform-Hosts |
| Plattform-Positivliste | 🔴 Die IP des AI-Hosts muss in der plattformseitigen Positivliste stehen, sonst findet kein Bezug statt |
/etc/kopens/ca/root.crt | Plattform-Trust-Anchor — aus der Antwort GET /api/credentials/tls der Plattform, root_pem. Vor dem Ablegen mit dem Fingerabdruck aus derselben Antwort root_fingerprint_sha256 abgleichen |
/etc/kopens/ca/CA.crt | inhaltsgleich mit root.crt. Die App liest unter diesem Namen |
Die ersten beiden Werte fließen in /etc/kopens/plantpulse-ai.env ein — in der Vorlage als Platzhalter vorhanden; bei interaktiver
Installation werden sie abgefragt oder als Umgebungsvariable übergeben. Compose mountet das gesamte
/etc/kopens/ca-Verzeichnis in den Container.
- Beide Werte sind Pflicht. Sind sie leer, verweigert compose den Start; fehlt nur einer, lehnt der Container ab.
- Auch Host-Skripte (z. B. DB-Provisionierung vor dem Start) beziehen dieselben beiden Werte sowie
root.crtvon der Plattform. In der Host-Env sind kein Plattform-Konto und kein Passwort hinterlegt. - Das Serverzertifikat wird ausschließlich über
root.crtgeprüft — fehlt die Datei, folgt FATAL, und es gibt keine Möglichkeit, die Prüfung abzuschalten. - Ob der Bezug erfolgreich war, erkennen Sie im Log — es werden nur Schlüsselname und Anzahl ausgegeben.
docker logs plantpulse-copilot-web 2>&1 | grep credentials:
→ Umgebungsvariablen konfigurieren · Fehlerbehebung
Video · Audio aktivieren — eine Zeile nach der Installation
Video-/Audio-Erfassung sowie die Spracheingabe im Chat sind standardmäßig deaktiviert. Zum Aktivieren tragen Sie in die
Host-Env die Zeile PI_MEDIA_ENABLED=true ein, beziehen mit bin/fetch-models.sh das Transkriptionsmodell (Aura-ASR-Turbo, ca. 1,5 GB) und führen
anschließend bin/restart.sh aus. Vorgehen und Prüfung finden Sie unter
Video-/Audio-Erfassung.
Nach der Installation
| Reihenfolge | Aufgabe | Befehl · Dokumentation |
|---|---|---|
| 1 | Standardpasswort ändern | Initiales Passwort ändern |
| 2 | Prüfen, ob der Stack läuft | bin/status.sh · bin/health.sh |
| 3 | Blockierende Stellen identifizieren | bin/doctor.sh |
Häufig verwendete Betriebsbefehle finden Sie unter bin/ — up.sh · down.sh · restart.sh ·
logs.sh · backup.sh · update.sh · passwd.sh. Näheres unter
Dienstbetrieb.
Verwandte Dokumente
- Systemanforderungen — Spezifikationen inklusive GPU
- Einzeilige Installation — der tatsächlich auszuführende Befehl
- Air-Gap-Installation — Netzwerke ohne Internetzugang
- Service-Port-Übersicht — welcher Port wofür steht