Zum Hauptinhalt springen

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.

Meistens reicht diese eine Zeile
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/ ← 형제 저장소
Die beiden Schwester-Repositories müssen «unbedingt» vorhanden sein

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.

WasWo
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​

KategorieContainerAufgabe
Eingangplantpulse-proxynginx (non-root). Nimmt 80 · 443 des Hosts sowie die HTTPS-Verwaltungskonsole (5960) entgegen und leitet sie nach innen weiter
Oberflächeplantpulse-copilot-web · plantpulse-admin-webCopilot-Oberfläche · Verwaltungskonsole (HTTP 5959)
Inferenzplantpulse-llm · plantpulse-emb · plantpulse-rerankvLLM — Generierung · Embedding · Re-Ranking
Gatewayplantpulse-litellm (4000)Bündelt alle Modellaufrufe an einem Ort
Dokumenteplantpulse-rag-api · plantpulse-lightrag · plantpulse-docling-serve · plantpulse-document-understanding-apiLiest · zerlegt · durchsucht Dokumente
Wissenplantpulse-neo4j (7474 · 7687) · plantpulse-qdrantWissensgraph · Vektorindex
Digital Threadplantpulse-digital-thread-api (7140, nicht am Host geöffnet) · plantpulse-digital-thread-neo4jSpiegel des Anlagengraphen und Connector-Registry · dessen dediziertes Neo4j (nicht am Host geöffnet)
Zeitreiheplantpulse-timeseries-insight-api (8970) · plantpulse-timeseries-insight-server (8980, nicht am Host geöffnet)Anomalieerkennung · Prognose
Visionplantpulse-vision-apiBildverständnis
Verwaltungplantpulse-admin-apiBackend der Verwaltungskonsole
Beobachtungplantpulse-phoenix (6006, nicht am Host geöffnet) · plantpulse-dcgmTrace-UI · GPU-Metriken
Transkriptionplantpulse-asr · plantpulse-asr-audioSprache → 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
Registryplantpulse-registry · plantpulse-registry-uiInterner 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.

SchrittAufgabeHost-global
1Locale (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)✅
2Swap deaktivieren (wird auch in /etc/fstab berücksichtigt)✅
3Installation von Docker CE + buildx + compose-v2-Plugin — wird übersprungen, falls bereits vorhanden
3bInstallation 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)
5OS-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✅
7Prüfung der Anmeldung bei der internen Registry (wird bei SKIP_LOGIN=1 übersprungen)
8Vorbereitung 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).

Auf Hosts, auf denen bereits andere Container laufen, wird «nur ausgegeben»

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 HostVerhalten
Wurde in diesem Lauf neu installiertdaemon.json wird mit Standardwerten (overlay2, DOCKER_DATA_DIR=/data1/docker-data) geschrieben
War bereits vorhandenSpeicher (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.

Ändern des Speicherorts lässt bestehende Container/Images «verschwinden»

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.

Standard ist «nur Vorbereitung»

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​

VariableBedeutung
START=1Geht über die Vorbereitung von .env hinaus bis zum Start — hilft auch beim automatischen Modellempfang und der Installationsprüfung
INTERACTIVE=1Fragt leere Werte ab (Standard ist nicht-interaktiv)
ENV_TEMPLATEOriginal-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=1Stoppt das Installationsprogramm, falls Vorlage und Architektur dieser Maschine nicht übereinstimmen. Überspringen Sie diese Prüfung nur bewusst, z. B. beim Testen neuer Hardware
HOST_TUNINGskip · 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_DIRSpeicherwurzel des in diesem Lauf neu installierten Dockers (Standard /data1/docker-data). Ein bereits vorhandenes Docker behält seine eigene Wurzel
ALLOW_DOCKER_RECONFIGURE=1Erlaubt Ä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_MINObergrenze (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=1Startet auf einer internetfähigen Maschine mit bereits heruntergeladenen Images
INSECURE_REGISTRYFügt eine interne Kunden-Registry (HTTP) der daemon.json-Positivliste hinzu
SKIP_PULL=1 kann zum Start mit «einem alten Build» führen

Der 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
AbgefragtTLS-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.)
ErzeugtGateway-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-Konto · Passwort werden nicht abgefragt (2026.10)

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“

TLS-SAN — die Zugriffsadresse ins Zertifikat eintragen

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
Menschen tippen keine acht Geheimnisse ein

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.

Ist der Inbound-Schlüssel leer, startet nichts

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.

SchrittAufgabe
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-ZugangsdatenVor 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 ModellempfangFehlende Modelle werden von model.kopens.ai bezogen, SHA256 geprüft und entpackt. Früher ein manueller Vorgang
Warten auf AntwortWartet 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üfungPrüft nicht nur, ob der Stack „läuft“, sondern ob er „funktioniert“ (siehe unten)
Ein grüner Stack mit leeren Werten ist schlimmer

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.

„21/21 running“ bedeutet nicht „funktioniert“

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»​

  1. bin/status.sh — 21/21 running · HTTP=200 (einundzwanzig im Standardstart)
  2. bin/verify-install.sh — OK 4 · FAIL 0. Schon ein einziges FAIL beendet die Installation als fehlgeschlagen
  3. 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
  4. 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
Zwei bekannte Fallstricke
  • 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 up setzt 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.

VorzubereitenWoher
PP_DATALAKE_ADMIN_URLhttps://<플랫폼 호스트>:4950 — dieser Host wird gleich zu PP_HOST
PP_DATALAKE_ADMIN_API_KEYgleichnamige 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.crtPlattform-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.crtinhaltsgleich 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.crt von der Plattform. In der Host-Env sind kein Plattform-Konto und kein Passwort hinterlegt.
  • Das Serverzertifikat wird ausschließlich über root.crt geprü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​

ReihenfolgeAufgabeBefehl · Dokumentation
1Standardpasswort ändernInitiales Passwort ändern
2Prüfen, ob der Stack läuftbin/status.sh · bin/health.sh
3Blockierende Stellen identifizierenbin/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​