Installation

Dies ist die Vorgehensweise zur Installation von PlantPulse Studio auf einem einzelnen Kundenserver. Das System besteht aus 4 Docker-Containern (Web · Server · Builder-Sidecar · PostgreSQL), und das Installationsskript übernimmt automatisch alles von der Docker-Installation bis zum Start.

Falls es sich um ein Air-Gap-Netzwerk ohne Internetzugang handelt, lesen Sie statt dieses Dokuments die Air-Gap-Installation.

---

1. Voraussetzungen

Serverspezifikationen

Punkt	Minimum	Empfohlen	Anmerkung
CPU	4 Kerne	8 Kerne oder mehr	Bei jeder App-Sitzung läuft ein Build
Arbeitsspeicher	8 GB	16 GB oder mehr	Siehe Tabelle unten
Festplatte	50 GB frei	100 GB oder mehr	Allein die Container-Images belegen ca. 6 GB
OS	Linux (x86_64)	RHEL 9 / Rocky 9 / Ubuntu 22.04 oder höher	systemd + Docker müssen lauffähig sein

Grundlage der Speicherberechnung — dies sind die im Stack fest hinterlegten Obergrenzen.

Container	Speicherobergrenze
studio-server (Orchestrator)	2 GB
agent-server (Builder-Sidecar)	2 GB
studio-web (nginx)	256 MB
postgres (Bundled-Modus)	Keine Begrenzung (tatsächliche Nutzung wenige hundert MB)
pro App-Sitzungs-Container	2 GB

Für jede App-Sitzung wird bei jedem Öffnen eines Projekts durch einen Benutzer ein Container gestartet, der automatisch nach 30 Minuten Inaktivität wieder freigegeben wird. Rechnen Sie 2 GB pro gleichzeitigem Bearbeiter zusätzlich ein.

Bei einem Ziel von 3–5 gleichzeitigen Benutzern

Mit 16 GB Arbeitsspeicher · 8 Kernen · 100 GB Festplatte liegen Sie komfortabel im grünen Bereich.

Software

• Docker Engine + Docker Compose v2 (v2.22 oder höher) Falls nicht installiert, installiert das One-Line-Installationsskript diese automatisch.
• curl, tar (in den meisten Distributionen standardmäßig enthalten)

Ports und Firewall

Der Stack läuft im Host-Netzwerk. Das heißt, die Container-Ports sind unverändert am Host geöffnet, sodass die Zugriffskontrolle ausschließlich über die Server-Firewall erfolgen muss.

Port	Zweck	Firewall
80	Studio-UI (nginx)	Offen
5171	App-Listener — Vorschau · Bereitgestellte Apps · QR-Zugriff	Offen (erforderlich)
5170	Studio-API	Wird intern von Web weitergeleitet — muss nicht geöffnet werden (nur für Diagnose)
5432	PostgreSQL (Bundled-Modus)	Nur an 127.0.0.1 gebunden — nicht öffnen
8000	Builder-Sidecar (agent-server)	Nur Loopback — niemals öffnen
5172	MCP-Tool-Bridge	Nur Loopback — niemals öffnen

Wenn Sie 5171 blockieren, öffnen sich Vorschau und bereitgestellte Apps nicht

Vorschau (/preview/…) und bereitgestellte Apps (/apps/…) werden aus Sicherheitsgründen an einem anderen Origin als Studio ausgeliefert (standardmäßig Port 5171). Dies verhindert, dass JavaScript einer per Chat erstellten App auf das Studio-Login-Token zugreifen kann. Wird 5171 nicht geöffnet, bleibt der Bildschirm leer.

8000 · 5172 haben keine Authentifizierung

Diese beiden Ports dienen ausschließlich der internen Kommunikation zwischen den Komponenten und verfügen über keine Authentifizierung. Werden sie nach außen exponiert, kann der gesamte Benutzer-Workspace gelesen und geschrieben werden. Der Stack bindet standardmäßig nur an Loopback, öffnen Sie sie aber auch in der Firewall auf keinen Fall.

Registry-Zugriff

Die Images werden aus der KOPENS-Registry (docker.kopens.io) bezogen. Melden Sie sich vor der Installation einmalig an. Das Konto wird vom KOPENS-Betriebsteam ausgestellt.

docker login docker.kopens.io

---

2. Datenbankauswahl

Entscheiden Sie sich vor der Installation für eine der beiden Optionen. Ein späterer Wechsel ist möglich, erfordert jedoch eine Datenmigration.

=== "(A) Gebündeltes PostgreSQL — Standard"

Der Stack startet einen PostgreSQL-Container mit. Dies ist die Standardeinstellung für Standorte ohne separaten DB-Server.

COMPOSE_PROFILES=bundled-pg
PG_DB=ppstudio
PG_USER=ppstudio
PG_PASSWORD=`<long-random-string>`

Die Daten werden unterhalb von DATA_ROOT/postgres gespeichert.

=== "(B) Externes/gemeinsam genutztes PostgreSQL"

Ist an Ihrem Standort bereits ein PostgreSQL für die Plattform vorhanden, können Sie doppelte Infrastruktur vermeiden. Löschen Sie die Zeile COMPOSE_PROFILES und geben Sie nur die Verbindungs-URL an — dann wird der PostgreSQL-Container gar nicht erst gestartet.

# COMPOSE_PROFILES-Zeile löschen
DATABASE_URL=postgres://`<user>`:`<password>`@`<db-host>`:5432/`<db-name>`

Es genügt, eine leere Datenbank bereitzustellen — die Tabellen werden vom Server beim ersten Start automatisch angelegt.

Behalten Sie das anfänglich festgelegte PG-Passwort bei

Wenn im Bundled-Modus bereits Daten angesammelt wurden und Sie danach nur PG_PASSWORD ändern, stimmt dies nicht mehr mit dem Konto im bestehenden Datenverzeichnis überein, und der Stack startet nicht. Um das Passwort zu ändern, müssen Sie zuerst das Kontopasswort innerhalb von PostgreSQL ändern.

---

3. Installation (One-Line · empfohlen)

Melden Sie sich als root am Server an und führen Sie eine einzige Zeile aus. Das Skript prüft und installiert Docker → lädt das Paket herunter → erzeugt .env → startet den Stack.

curl -fsSL https://product.kopens.io/plantpulse-studio/install.sh | sudo bash

Der Installationsort ist /opt/kopens/plantpulse-studio-docker, und alle weiteren Betriebsbefehle werden in diesem Verzeichnis ausgeführt.

Unbeaufsichtigte Installation mit vorab festgelegten Werten

Umgebungsvariablen müssen vor bash gesetzt werden, damit sie über die Pipe übergeben werden.

curl -fsSL https://product.kopens.io/plantpulse-studio/install.sh \
  | sudo PLATFORM_API_TARGET=https://192.168.0.41 \
         DATA_ROOT=/data1/pp-studio \
         ANTHROPIC_API_KEY=sk-ant-... \
         bash

Werte interaktiv abfragen lassen

curl -fsSL https://product.kopens.io/plantpulse-studio/install.sh | sudo INTERACTIVE=1 bash

Für jedes leere Feld erscheint eine Eingabeaufforderung (Datenwurzel · PG-Passwort · Plattform-Adresse · Admin-Konto usw.).

Erneutes Ausführen ist sicher

Wird das Installationsskript auf demselben Server erneut ausgeführt, wird nur der Code aktualisiert; .env und lokale Backups (dist/) bleiben erhalten. Es kann problemlos auch für Upgrades verwendet werden.

Wenn das Installationsskript einen 404-Fehler oder eine veraltete Version liefert

Möglicherweise liegt noch ein CDN-Cache vor. Hängen Sie ?v=$(date +%s) an die URL an und laden Sie erneut.

---

4. Installation (manuell)

Dies gilt, wenn Sie das Paket bereits heruntergeladen haben oder .env selbst erstellen möchten.

cd /opt/kopens/plantpulse-studio-docker
sudo cp .env.example /etc/kopens/plantpulse-studio.env
sudo vi /etc/kopens/plantpulse-studio.env   # 아래 표를 보고 값 채우기
sudo chmod 600 /etc/kopens/plantpulse-studio.env
bash bin/start.sh

Die maßgebliche Konfiguration liegt einzig in /etc/kopens/plantpulse-studio.env

Die Umgebungsvariablen-Datei liegt nicht im Installationsverzeichnis, sondern außerhalb des Repo-Baums unter /etc/kopens/plantpulse-studio.env. Die Berechtigung ist 0600. Die drei Produkte platform · ai · studio verwenden /etc/kopens/plantpulse-<product>.env nach derselben Konvention.

Die Datei .env im Wurzelverzeichnis des Installationsverzeichnisses ist ein veralteter Pfad. Weder compose noch die übrigen Skripte lesen diese Datei noch, sodass eine Änderung dort den Stack nicht beeinflusst. Bei bestehenden Installationen wird .env von bin/install.sh an den neuen Pfad verschoben (nicht neu erzeugt — würde man sie neu erzeugen, hätte die DB weiterhin das alte Passwort, während env den neuen Standardwert enthält, was beim nächsten Neustart zum Absturz führt).

Wichtige Umgebungsvariablen

Punkt	Beschreibung	Standardwert
REGISTRY	Image-Registry. Leer lassen, um ohne Pull nur lokale Images zu verwenden (Air-Gap)	docker.kopens.io/ps
TAG	Image-Tag. Zum Fixieren einer bestimmten Version wie 2026.08 angeben	latest
DATA_ROOT	Pfad, unter dem alle Daten (Workspace · Build · Status · DB) gespeichert werden	/var/lib/pp-studio
PLATFORM_API_TARGET	Adresse der PlantPulse-Plattform, an die echte Daten und Authentifizierung delegiert werden	https://192.168.0.41
APPS_PORT	App-Listener-Port (Vorschau · bereitgestellte Apps)	5171
PP_LANG	Standardsprache der Weboberfläche ko / en	en
PP_TZ	Zeitzone (IANA-ID). Grundlage für die Interpretation von "heute · gestern · letzte Woche"	Asia/Seoul
STUDIO_CORS_ORIGINS	Nur angeben, wenn die API von einer anderen Domain aus aufgerufen wird. Standardmäßig blockiert	leer
COMPOSE_PROFILES / DATABASE_URL	Datenbankauswahl — siehe Abschnitt 2 oben	bundled-pg
ANTHROPIC_API_KEY usw.	AI-/Plattform-Schlüssel — siehe Verwaltung von Geheimnissen	leer

Konten und Rollen werden nicht über Umgebungsvariablen übertragen

STUDIO_LOCAL_USERS · STUDIO_ADMINS · STUDIO_VIEWERS sind weggefallen (2026-08-18). Wenn der Server startet und noch kein einziges Konto existiert, wird ein Bootstrap-Administrator in der DB angelegt; danach werden Konten unter Einstellungen → Benutzerverwaltung in der App hinzugefügt/entfernt und Rollen (Administrator / Builder / Betrachter) vergeben. Siehe unten 7. Erste Anmeldung.

Für Standorte mit koreanischer Sprache tragen Sie PP_LANG=ko selbst ein

Die vom One-Line-Setup erzeugte .env enthält keine Zeilen PP_LANG · PP_TZ, sodass die Standardwerte (en / Asia/Seoul) angewendet werden. Um mit koreanischer Sprache zu starten, fügen Sie .env die Zeile PP_LANG=ko hinzu und bash bin/restart.sh.

Nach dem Ändern von .env unbedingt bin/restart.sh ausführen

docker restart liest .env nicht erneut ein. Dies ist eine typische Falle, bei der man lange nach dem Grund sucht, warum sich die Werte nicht auswirken. Details finden Sie unter Verwaltung von Geheimnissen.

---

5. Überprüfung der Stack-Konfiguration

Nach der Installation sollten 4 Container laufen.

Container	Rolle
pp-studio-web	Studio-UI (nginx :80) — statische Oberfläche + API-Proxy
pp-studio-server	Orchestrator (:5170) — Agent · Sitzung · Bereitstellung · App-Listener (:5171)
pp-studio-agent-server	Builder-Sidecar — Coding-Engine, die den App-Code schreibt
pp-studio-postgres	Gebündeltes PostgreSQL (startet nicht, wenn eine externe DB verwendet wird)

Zusätzlich wird pro Projekt ein App-Sitzungs-Container gestartet, sobald ein Benutzer das Projekt öffnet. Dies ist kein Stack-Container, sondern wird bei Bedarf vom Server erzeugt und nach 30 Minuten Inaktivität wieder freigegeben.

---

6. Startüberprüfung

cd /opt/kopens/plantpulse-studio-docker

bash bin/status.sh          # 컨테이너 상태 + 헬스 + 세션 컨테이너 수
curl -s localhost:5170/health

Unmittelbar nach der Installation empfiehlt es sich, einmalig ein umfassendes Prüfskript auszuführen. Dieses überprüft Health · Web-Antwort · tatsächliche Anmeldung · Sitzungs-Laufzeit-Image · Container-Status und bricht mit einem Fehler ab, sobald auch nur ein Punkt fehlschlägt.

bash bin/smoke-install.sh

✓ health
✓ client-config → {"lang":"ko",...}
✓ web 200
✓ 로그인(부트스트랩 계정)
✓ 세션 런타임 이미지
✓ 컨테이너 running(...)
✅ 설치 스모크 통과

Sitzungs-Laufzeit-Image

Die App-Sitzungs-Container verwenden das Image plantpulse-studio-runtime. bin/start.sh lädt es automatisch herunter und taggt es; schlägt dies fehl, erscheint die Warnung ⚠️ 세션 런타임 이미지 없음 und das Öffnen von Projekten schlägt fehl. Prüfen Sie in diesem Fall den Anmeldestatus bei der Registry und führen Sie bash bin/start.sh erneut aus.

---

7. Erste Anmeldung

Rufen Sie im Browser http://<server-ip>/ auf.

Startet der Server erstmals ohne ein einziges vorhandenes Konto, wird ein Bootstrap-Administrator in der DB angelegt.

Punkt	Wert
ID	admin
Passwort	admin123!

Dies erscheint auch im Boot-Log — 부트스트랩 관리자 생성: admin — 로그인 후 비밀번호를 바꿀 것.

Ändern Sie zuerst dieses Passwort

Bei jeder Installation gilt derselbe Wert. Ändern Sie es unmittelbar nach dem Anmelden unter Einstellungen → Benutzerverwaltung (Passwort-Reset, mindestens 6 Zeichen). Ein Ändern der Umgebungsvariablen-Datei bewirkt keine Änderung — der Server prüft beim Anmelden in der Reihenfolge ① DB → ② Umgebungsvariablen und stoppt, sobald es in der DB gefunden wird.

Nach der Anmeldung zu erledigen:

1. Einstellungen → Benutzerverwaltung — Passwort des Bootstrap-Administrators ändern, Benutzerkonten für den Vor-Ort-Einsatz anlegen, Rollen (Administrator / Builder / Betrachter) zuweisen
2. Passwort-/API-Schlüssel-Wechsel — DB-Konto und AI-Schlüssel zusammen über bin/passwd.sh rotieren. Dies muss nur einmal während der Inbetriebnahme erfolgen
3. Einstellungen → AI — AI-Provider und Verbindungsstatus des Schlüssels prüfen
4. Einstellungen → Plattform — Verbindung zu Plattform-Adresse und -Schlüssel prüfen (erforderlich für den Abruf echter Daten)

Detaillierte Bildschirmbeschreibungen finden Sie unter Erste Schritte und Einstellungen (Administrator).

8. Alltägliche Betriebsbefehle

Alle Befehle werden im Installationsverzeichnis (/opt/kopens/plantpulse-studio-docker) ausgeführt.

bash bin/start.sh            # 시작(레지스트리에서 최신 이미지 pull 포함)
bash bin/stop.sh             # 중지 — 데이터는 그대로 보존, 세션 컨테이너도 정리
bash bin/restart.sh          # 재기동(.env 변경 반영)
bash bin/status.sh           # 상태 요약
bash bin/logs.sh             # 서버 로그 팔로우(기본 studio-server)
bash bin/logs.sh studio-web  # 특정 서비스 로그

Um nur die Sitzungs-Container separat anzuzeigen:

docker ps --filter label=plantpulse-studio=1

---

9. Aktualisierung

bin/start.sh aktualisiert die Images durch erneutes Herunterladen aus der Registry. Führt man das Installationsskript erneut aus, werden auch die Betriebsskripte mit aktualisiert (.env · Backups bleiben erhalten).

=== "Nur Images aktualisieren"

cd /opt/kopens/plantpulse-studio-docker
bash bin/start.sh

=== "Auch das Paket aktualisieren"

curl -fsSL https://product.kopens.io/plantpulse-studio/install.sh | sudo bash

Version fixieren

Die Versionsangabe erfolgt im Format YYYY.MM (z. B. 2026.08). In Betriebsumgebungen, in denen keine automatische Aktualisierung gewünscht ist, fixieren Sie den Tag in .env.

TAG=2026.08

Vor der Aktualisierung sichern

Führen Sie zuerst bash bin/backup.sh aus. Die Vorgehensweise finden Sie unter Backup und Wiederherstellung.

Verifizierung der Image-Signatur (optional)

Sie können prüfen, ob das bereitgestellte Image tatsächlich von KOPENS signiert wurde. cosign muss installiert sein.

cd /opt/kopens/plantpulse-studio-docker
bash bin/verify-images.sh

[verify] ✅ docker.kopens.io/ps/plantpulse-studio-server:2026.08
[verify] ✅ docker.kopens.io/ps/plantpulse-studio-web:2026.08
[verify] ✅ docker.kopens.io/ps/plantpulse-studio-runtime:2026.08

---

Nächste Schritte

• Verwaltung von Geheimnissen — Sichere Eingabe von AI-/Plattform-Schlüsseln
• Domain und Reverse-Proxy — Bereitstellung über Domain·HTTPS statt IP
• Backup und Wiederherstellung — Installation der automatischen Sicherung und Wiederherstellungsproben
• Fehlerbehebung — Tabelle mit Ursachen und Maßnahmen nach Symptom