Installieren und umziehen
Installation mit Docker
Flowplan läuft als ein einziger Container mit SQLite und einem Datenverzeichnis. Postgres, Redis oder ein separater Suchdienst werden nicht gebraucht – PostgreSQL und mehrere Instanzen sind möglich, aber optional.
8 Min. Lesezeit
Auf dieser Seite

Mehr zum Thema: Mit einem Klick bereitstellen
Voraussetzungen
- Ein Server mit Docker und einem dauerhaften Volume. Die Texterkennung gescannter PDFs braucht beim Hochladen kurzzeitig spürbar CPU.
- Schon eine Instanz auf einem anderen Server? Dann nach der Installation umziehen statt neu anfangen.
- Eine Domain mit HTTPS über einen Reverse Proxy (Traefik, Caddy, nginx, Coolify, Pangolin …). Zum reinen Ausprobieren geht es auch ohne, siehe Ohne HTTPS.
- Optional ein OpenID-Connect-Anbieter für Single Sign-on. Ohne ihn melden sich Personen mit E-Mail und Passwort oder Passkey an, siehe Anmeldung.
- Optional: ein S3-kompatibler Speicher für Dateien und die laufende Datenbanksicherung, siehe Speicher, S3 und Sicherung.
- Optional: eine PostgreSQL-Datenbank statt SQLite, siehe PostgreSQL. Wie viel Hardware du für wie viele Personen brauchst, steht unter Dimensionierung.
Mit Docker Compose
Flowplan ist Open Source (AGPL-3.0). Das fertige Image liegt in der GitHub Container Registry, für linux/amd64 und linux/arm64:
| Tag | Inhalt |
|---|---|
ghcr.io/yannicschuller/flowplan:latest | Neueste Version (Release) |
ghcr.io/yannicschuller/flowplan:0.7.0 | Feste Version (derzeit 0.7.0), auch als :0.7 und :0 |
ghcr.io/yannicschuller/flowplan:beta | Letzter manuell gestarteter Entwicklungsstand oder ein neueres Release – zum Ausprobieren, nicht für den Betrieb |
Compose-Datei und Beispielkonfiguration herunterladen:
mkdir flowplan && cd flowplan curl -O https://raw.githubusercontent.com/yannicschuller/flowplan/main/compose.yaml curl -o .env https://raw.githubusercontent.com/yannicschuller/flowplan/main/.env.exampleIn
.envmindestens die öffentliche Adresse setzen:APP_URL=https://flowplan.example.com # Empfohlen, sobald die Adresse aus dem Internet erreichbar ist: openssl rand -hex 24 FLOWPLAN_SETUP_TOKEN=Mit
FLOWPLAN_SETUP_TOKENlegst du das erste Konto überhttps://flowplan.example.com/register?setup=<token>an; ohne den Link bietet die neue Instanz weder Registrierung noch Wiederherstellen an. Fehlt der Token und istAPP_URLkeine lokale Adresse, warnt Flowplan beim Start im Log und auf dem Einrichtungsbildschirm.Für Single Sign-on zusätzlich
OIDC_ISSUER,OIDC_CLIENT_ID,OIDC_CLIENT_SECRETundOIDC_ADMIN_GROUP(siehe Anmeldung); für E-Mails (Einladungen, Passwort vergessen) dieSMTP_*-Werte aus der Konfiguration.Starten:
docker compose up -d
Der Container lauscht auf Port 3000 (in der Compose-Datei nur an 127.0.0.1 gebunden, damit der Proxy davor sitzt). Das Volume flowplan-data auf /app/data hält alle Inhalte unabhängig vom Container. Eine feste Version wählst du mit FLOWPLAN_VERSION=0.7.0 in der .env.
Eine Instanz öffnet direkt mit der Anmeldung. Die Webseite flowplan.org und diese Dokumentation sind eigene Projekte; die gehostete Instanz läuft unter app.flowplan.org.
Image selbst bauen
Aus dem Quellcode (github.com/yannicschuller/flowplan (öffnet in neuem Tab)):
git clone https://github.com/yannicschuller/flowplan.git && cd flowplan
cp .env.example .env
docker compose up -d --buildOder ohne Compose:
docker build -t flowplan:latest .
docker run -d --name flowplan \
-p 127.0.0.1:3000:3000 \
-v flowplan-data:/app/data \
--env-file .env \
flowplan:latestBuild-Argumente: PG_CLIENT_MAJOR (Standard 18) wählt die Version von pg_dump, pg_restore und psql im Image – mindestens die Hauptversion deines PostgreSQL-Servers (PostgreSQL). FLOWPLAN_SKIP_TYPECHECK=1 ist nur für die Entwicklung gedacht: Es überspringt die TypeScript-Prüfung beim Build, wenn sie wie in unserem CI schon gelaufen ist. FLOWPLAN_DEPLOYMENT_ID legt die Deployment-ID fest (Standard v<Version>-<Commit>, off: keine), mit der Browser bei einem Rolling Update keine Versionen mischen (Hochverfügbarkeit). Seit 0.10.0
Das Image enthält Node und Litestream für die S3-Sicherung, auf Debian 13. Ein echtes curl ist nicht dabei; für Healthchecks, die im Container curl aufrufen (etwa der HTTP-Check von Coolify), steht ein kleiner Ersatz bereit, der genau das kann. Seit 0.9.7 Flowplan läuft darin als UID 1000 (Benutzer node) oder, als root gestartet, als der Benutzer aus PUID/PGID Seit 0.10.0 – nie als root (Volume-Rechte).
Erster Start
https://flowplan.example.com/api/healthaufrufen – die Antwort ist200mit"status":"ok".- Die Adresse im Browser öffnen: Eine neue Instanz bietet Konto erstellen an. Dieses erste Konto verwaltet die Instanz. Ist die Adresse aus dem Internet erreichbar, setze vorher
FLOWPLAN_SETUP_TOKENund lege das Konto über/register?setup=<token>an – sonst könnte dir jemand zuvorkommen (Anmeldung). (Mit Single Sign-on: Mit SSO anmelden; Admin ist, wer in der Gruppe ausOIDC_ADMIN_GROUPist.) - In der Seitenleiste unter Administration Instanzname, Upload-Grenze, Registrierung und die weiteren Einstellungen setzen.
Umzug oder Neuinstallation? Statt des ersten Kontos bietet der Einrichtungsbildschirm Aus Sicherung wiederherstellen: eine Sicherungsdatei hochladen oder die neueste Sicherung aus S3 oder per SFTP holen, verschlüsselte mit dem Schlüssel der alten Instanz. Danach meldest du dich mit den Konten der Sicherung an (Beim Einrichten wiederherstellen). Für einen Umzug von einer laufenden Instanz gibt es außerdem Instanz umziehen.
Mit SQLite läuft genau eine Instanz. Mehrere Replikate würden dieselbe SQLite-Datei beschreiben. Nicht einfach horizontal skalieren; bei Updates den alten Container vor dem neuen stoppen. Mehrere Instanzen gehen nur im Cluster-Modus mit PostgreSQL, Redis und S3.
Ohne HTTPS
Nur zum Ausprobieren: Flowplan läuft auch unter einer reinen http://-Adresse, etwa APP_URL=http://192.168.1.20:3000 im eigenen Netz. APP_URL muss dann genau diese Adresse sein – mit http:// und Port.
Die Anmeldeseite und Administration → Instanz zeigen dann den Hinweis „Diese Instanz läuft ohne HTTPS“. Für einen Test ist das in Ordnung, für den echten Betrieb nicht:
- Passwörter gehen unverschlüsselt durchs Netz – jeder im selben Netz kann sie mitlesen.
- Passkeys, die Offline-Kopie, Push sowie Kamera, Mikrofon und Zwischenablage gibt es im Browser nur über HTTPS. Flowplan blendet sie dann aus oder sagt, warum sie fehlen.
- Die Apps für iPhone, iPad und Android verbinden sich ohne HTTPS nur mit einer Instanz im lokalen Netz (z. B.
http://192.168.1.20:3000,http://nasoderhttp://nas.local) und warnen vorher. Auf iPhone und iPad gehen.lan- oder.home.arpa-Namen nicht – dort die IP-Adresse eintragen. Siehe Instanz im eigenen Netz ohne HTTPS. - Cookies tragen kein
Secure-Kennzeichen, und der Browser stuft Anfragen nicht auf HTTPS hoch.
Unter http://localhost oder http://127.0.0.1 auf dem eigenen Rechner erscheint kein Hinweis: Browser behandeln diese Adressen wie eine sichere Verbindung.
Für den echten Betrieb einen Reverse Proxy mit Zertifikat davorsetzen (siehe Coolify und Reverse Proxy) und APP_URL auf die https://-Adresse umstellen. Mit Caddy reichen zwei Zeilen; Caddy holt das Zertifikat selbst.
Bis 0.8.0 verlangte Flowplan HTTPS stillschweigend: Unter einer http://-Adresse fehlten Gestaltung und Skripte, und das Registrierungsformular blieb einfach stehen. Das ist behoben – Formulare mit Passwort senden außerdem nie mehr Zugangsdaten in der Adresszeile.
Aktualisieren
Gibt es ein neueres Release, zeigt die Administration einen Hinweis mit der neuen Versionsnummer und einem Link zu den Änderungen (abschaltbar mit FLOWPLAN_UPDATE_CHECK=false, siehe Konfiguration). Mit dem Image-Tag :latest genügt dann:
docker compose pull
docker compose up -dBeim selbst gebauten Image stattdessen git pull und docker compose up -d --build.
Beim Start migriert Flowplan die Datenbank selbst. Vorher eine Sicherung anlegen (siehe Speicher, S3 und Sicherung); ein Zurückgehen auf eine ältere Version nach einer Migration ist nicht vorgesehen.
Nach dem Update sieht jede Person beim nächsten Öffnen von Flowplan einmal Neu in Flowplan: die Versionshinweise aller Versionen seit der, die sie zuletzt gesehen hat – die neueste aufgeklappt, ältere zugeklappt, gegliedert in Breaking Changes, Sicherheit, Neu, Verbessert und Fehlerbehebungen; Breaking Changes stehen hervorgehoben oben. Schließen (oder Esc) und Einstellungen blenden den Dialog für diese Version aus. Die Hinweise sind Teil des Images: Flowplan fragt dafür nicht im Internet nach. Neue Konten beginnen bei der laufenden Version und sehen keine älteren Hinweise; Konten aus der Zeit vor 0.9.4 sehen nach dem Update auf 0.9.4 nur dessen Hinweise. Beta-Images (:beta) zeigen die Hinweise bis zu der Version, die sie melden – die Hinweise des kommenden Release erst mit diesem. Was jemand zu sehen bekommt, stellt er unter Einstellungen → Darstellung & Sprache → Neuigkeiten nach Updates ein (Hell und dunkel), den Standard für neue Konten legen Admins unter Administration → Instanz fest (Instanz). Die vollständige Liste aller Änderungen steht im Changelog auf GitHub (öffnet in neuem Tab).
Auf 0.7.0 aktualisieren
Von Hand ist nichts zu tun; die neuen Tabellen (etwa für Idempotenz-Schlüssel und den Push-Relay) legt Flowplan beim Start an. Was sich für den Betrieb ändert:
- API-Beschreibung nur noch mit Anmeldung:
/api/openapi.jsonund/api/docsbrauchen eine Anmeldung oder ein API-Token. Öffentlich wie bisher mitFLOWPLAN_PUBLIC_API_DOCS=true(siehe OpenAPI und SDKs). - Gesundheitsprüfung knapper:
/api/healthantwortet ohne Token nur noch mit{"service":"flowplan","status":"ok"}; Details gibt es mitFLOWPLAN_METRICS_TOKEN(siehe Healthcheck). - Push an die Apps über den Push-Relay: Benachrichtigungen an die Apps laufen Ende-zu-Ende-verschlüsselt über
push.flowplan.org. Dafür mussAPP_URLdie öffentliche HTTPS-Adresse sein und ausgehendes HTTPS zum Relay möglich – siehe Push-Relay. - Nutzungsstatistik: Die Überwachung zählt Anfragen, aktive Personen und Speicher – nur Zahlen. Abschalten mit
FLOWPLAN_METRICS=offoder in der Administration (siehe Statistik).
Kubernetes (Helm)
Das Chart liegt im Repository unter deploy/helm/flowplan (öffnet in neuem Tab). Standardmäßig läuft Flowplan dort als genau ein Pod (SQLite) mit einem Volume für /app/data; Updates ersetzen den Pod mit kurzer Unterbrechung (Strategie Recreate). Das Chart installiert die Flowplan-Version seiner appVersion; eine andere wählst du mit --set image.tag=…. Alles Weitere – mehrere Pods, Umzug von SQLite, Updates, Sicherungen, Fehlersuche – steht auf der Seite Kubernetes. Seit 0.10.0
kubectl create namespace flowplan
kubectl -n flowplan create secret generic flowplan-env \
--from-literal=FLOWPLAN_ENCRYPTION_KEY="$(openssl rand -base64 32)"
helm install flowplan deploy/helm/flowplan -n flowplan \
--set appUrl=https://flowplan.example.org \
--set existingSecret=flowplan-env \
--set ingress.enabled=true \
--set ingress.hosts[0].host=flowplan.example.org- OIDC, SMTP und S3 setzt du über
oidc.*,smtp.*unds3.*; Geheimnisse nur imexistingSecret(Schlüssel = Namen der Umgebungsvariablen) – als Wert nimmt das Chart keine. Seit 0.10.0 Weitere Variablen überenv. appUrlist Pflicht (oder kommt aus dem ersten Ingress-Host).- Das Chart erzeugt einen zufälligen
FLOWPLAN_SETUP_TOKENim Secretflowplan-setup(bleibt bei Upgrades erhalten; ein eigenes Secret mitsetupToken.existingSecret). Seit 0.10.0 Das erste Konto legst du über den Einrichtungslink an, denhelm installam Ende ausgibt:https://flowplan.example.org/register?setup=<token>, den Token liestkubectl -n flowplan get secret flowplan-setup -o jsonpath='{.data.FLOWPLAN_SETUP_TOKEN}' | base64 -d. - Ein Block- oder lokales Volume verwenden, kein NFS (SQLite).
- Health-Checks laufen über
/api/health; der Pod läuft als Nutzer 1000 ohne zusätzliche Rechte auf einem schreibgeschützten Root-Dateisystem. Seit 0.10.0helm test flowplanprüft die Erreichbarkeit. - Das Volume bleibt beim Deinstallieren erhalten.
- Aktualisieren: im Repository
git pull, dannhelm upgrade flowplan deploy/helm/flowplan -n flowplan -f my-values.yaml.
Alle Werte erklärt das README des Charts. Mehrere Pods mit PostgreSQL, Redis und S3 (cluster.enabled=true): siehe Cluster-Modus. Die Datenbankrolle in DATABASE_URL sollte dabei die Datenbank besitzen, aber kein Superuser sein (Rolle ohne Superuser-Rechte).
Ohne Docker
Node.js 22.13 oder neuer (Node 24 LTS empfohlen):
npm ci
npm run build
FLOWPLAN_DATA_DIR=/var/lib/flowplan npm startFür die lokale Entwicklung reicht npm run dev. Der Entwicklungsmodus bietet zusätzlich Lokalen Arbeitsbereich öffnen an, ein gemeinsames Beispielkonto; im Produktionsmodus gibt es diesen Zugang nicht.
Weiter
- Konfiguration: alle Umgebungsvariablen.
- Coolify und Reverse Proxy: Betrieb hinter Traefik, Coolify oder Pangolin.
- Instanz umziehen: auf einen anderen Server, mit Beispiel für Hetzner Cloud.
- PostgreSQL und Cluster-Modus: für größere Teams.