Zum Inhalt
flowplanDokumentationCommunityMarketplaceZur Startseite

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
  1. Voraussetzungen
  2. Mit Docker Compose
  3. Image selbst bauen
  4. Erster Start
  5. Ohne HTTPS
  6. Aktualisieren
  7. Auf 0.7.0 aktualisieren
  8. Kubernetes (Helm)
  9. Ohne Docker
  10. Weiter
Aufbau einer Instanz: Browser, Desktop-Apps und die Apps für iOS und Android verbinden sich über einen Reverse Proxy mit HTTPS mit dem Flowplan-Container. Darin schreibt der Next.js-Server in SQLite und ein Uploads-Volume; Litestream sichert die Datenbank laufend nach S3, die Uploads werden dorthin gespiegelt. Optional angebunden sind OIDC oder LDAP, SMTP, ein KI-Anbieter und das Push-Relay, das Mitteilungen Ende-zu-Ende-verschlüsselt an die Apps bringt. (in voller Größe öffnen)
Eine Instanz: ein Container hinter dem Reverse Proxy, alles Weitere optional.

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:

TagInhalt
ghcr.io/yannicschuller/flowplan:latestNeueste Version (Release)
ghcr.io/yannicschuller/flowplan:0.7.0Feste Version (derzeit 0.7.0), auch als :0.7 und :0
ghcr.io/yannicschuller/flowplan:betaLetzter manuell gestarteter Entwicklungsstand oder ein neueres Release – zum Ausprobieren, nicht für den Betrieb
  1. 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.example
  2. In .env mindestens 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_TOKEN legst du das erste Konto über https://flowplan.example.com/register?setup=<token> an; ohne den Link bietet die neue Instanz weder Registrierung noch Wiederherstellen an. Fehlt der Token und ist APP_URL keine 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_SECRET und OIDC_ADMIN_GROUP (siehe Anmeldung); für E-Mails (Einladungen, Passwort vergessen) die SMTP_*-Werte aus der Konfiguration.

  3. 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.

Hinweis

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 --build

Oder 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:latest

Build-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

  1. https://flowplan.example.com/api/health aufrufen – die Antwort ist 200 mit "status":"ok".
  2. 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_TOKEN und 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 aus OIDC_ADMIN_GROUP ist.)
  3. 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.

Achtung

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://nas oder http://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.

Hinweis

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 -d

Beim 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.json und /api/docs brauchen eine Anmeldung oder ein API-Token. Öffentlich wie bisher mit FLOWPLAN_PUBLIC_API_DOCS=true (siehe OpenAPI und SDKs).
  • Gesundheitsprüfung knapper: /api/health antwortet ohne Token nur noch mit {"service":"flowplan","status":"ok"}; Details gibt es mit FLOWPLAN_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 muss APP_URL die ö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=off oder 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.* und s3.*; Geheimnisse nur im existingSecret (Schlüssel = Namen der Umgebungsvariablen) – als Wert nimmt das Chart keine. Seit 0.10.0 Weitere Variablen über env.
  • appUrl ist Pflicht (oder kommt aus dem ersten Ingress-Host).
  • Das Chart erzeugt einen zufälligen FLOWPLAN_SETUP_TOKEN im Secret flowplan-setup (bleibt bei Upgrades erhalten; ein eigenes Secret mit setupToken.existingSecret). Seit 0.10.0 Das erste Konto legst du über den Einrichtungslink an, den helm install am Ende ausgibt: https://flowplan.example.org/register?setup=<token>, den Token liest kubectl -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.0 helm test flowplan prüft die Erreichbarkeit.
  • Das Volume bleibt beim Deinstallieren erhalten.
  • Aktualisieren: im Repository git pull, dann helm 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 start

Fü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

War das hilfreich?
JaDanke!
Nein – sag uns, was fehlt

Fehler gefunden oder etwas fehlt?Auf GitHub bearbeiten