Planka selbst hosten: Kanban-Board mit Docker Compose
So installieren Sie Planka 2 auf einem VPS mit Docker Compose, Postgres und Traefik. Wichtig: BASE_URL und Admin-Variablen, sonst schlagen Logins fehl.
Was Sie durch das Self-Hosting von Planka erhalten
Mit dem Self-Hosting von Planka erhält Ihr Team ein Kanban-Board mit dem Karten-, Listen- und Label-Modell, das viele bereits aus Trello kennen, auf einem von Ihnen kontrollierten VPS. Es gibt keine Beschränkung der Anzahl von Benutzern und keine Abrechnung pro Benutzer, weil nur die Kosten für den Server anfallen. In dieser Anleitung wird Planka mit Docker Compose hinter Traefik bereitgestellt. Postgres speichert die Daten, und ein benanntes Volume nimmt alle von Benutzern hochgeladenen Dateien auf.
Planka 2 wird unter der eigenen Fair Use License des Projekts veröffentlicht. Das Projekt bezeichnet diese Lizenz als source-available und nicht als Open Source. Der Betrieb für interne Projekte der eigenen Organisation ist zulässig. Wenn Sie Planka Dritten als kommerziellen gehosteten Dienst anbieten, benötigen Sie eine Pro- oder Enterprise-Lizenz.
Die Anleitung richtet sich an ein Team mit zwei bis fünf Personen, das den kostenlosen Tarif von Trello verlässt. Wenn Sie noch entscheiden, welches Board Sie einsetzen möchten, lesen Sie zuerst den Vergleich selbst gehosteter Trello-Alternativen. Diese Anleitung setzt voraus, dass die Entscheidung bereits getroffen wurde, und behandelt nur die Bereitstellung.
Sie benötigen einen VPS mit Docker Engine und dem Compose-Plugin sowie einen DNS-A-Eintrag, der auf diesen Server zeigt. Außerdem muss auf diesem Server bereits eine Traefik-Instanz TLS (Transport Layer Security) terminieren. Wenn Traefik noch nicht vorhanden ist, richten Sie zuerst einen Traefik-Reverse-Proxy vor mehreren Compose-Anwendungen ein. Lesen Sie außerdem die Grundlagen von Docker Compose für einen VPS, wenn Ihnen die folgende Datei nicht vertraut ist.
Wie viel VPS benötigt Planka?
Die technische FAQ des Projekts empfiehlt für kleine Teams mindestens 2 GB RAM und 10 GB Speicherplatz. Betrachten Sie diese Werte daher als Ausgangspunkt und nicht als Messwert.
Tatsächlich laufen nur wenige Komponenten: ein Node.js-Prozess stellt die API und das gebaute Frontend bereit. Ein Postgres-Server speichert die Daten. Er führt einen überwachenden Prozess sowie für jede offene Verbindung einen Backend-Prozess aus. Außerdem läuft im Planka-Container ein kleiner Proxy-Prozess, der ausgehende Anfragen filtert. Ein Tarif mit 2 GB entspricht der RAM-Empfehlung des Projekts für kleine Teams. Ein Board benötigt nur wenig zusätzliche Ressourcen. Wenn derselbe VPS auch die Dokumente Ihres Teams aufnehmen soll, dimensionieren Sie ihn zuerst für diese Anwendung: AFFiNE als Notion-ähnlichen Arbeitsbereich betreiben benötigt bereits für sich einige Gigabyte, bevor Planka weiteren Speicher beansprucht.
Dimensionieren Sie den Speicherplatz vor dem Arbeitsspeicher, weil Anhänge am stärksten wachsen. Messen Sie Ihre eigene Instanz, statt sich auf diesen Abschnitt zu verlassen:
docker stats --no-stream
docker system df -vDer erste Befehl zeigt den aktuellen Speicher- und CPU-Verbrauch pro Container. Der zweite zeigt, wie viel Speicherplatz jedes Volume belegt. Führen Sie beide Messungen nach einer normalen Arbeitswoche durch, nicht am Tag der Installation. Ein ungenutztes Board liefert keine verwertbaren Informationen über Ihr Team.
Compose-Datei schreiben
Erstellen Sie das Verzeichnis und übernehmen Sie dessen Besitz, damit Sie diese Dateien nie über sudo bearbeiten müssen.
sudo mkdir -p /opt/planka
sudo chown "$USER":"$USER" /opt/planka
cd /opt/plankaGenerieren Sie die Secrets in einer .env-Datei neben der Compose-Datei. Compose liest diese Datei automatisch und ersetzt die Platzhalter durch die enthaltenen Werte.
umask 077
{
printf 'SECRET_KEY=%s\n' "$(openssl rand -hex 64)"
printf 'POSTGRES_PASSWORD=%s\n' "$(openssl rand -hex 24)"
printf 'ADMIN_PASSWORD=%s\n' "$(openssl rand -hex 12)"
} > .env
chmod 600 .envopenssl rand -hex ist beabsichtigt. Eine Hexadezimalzeichenfolge enthält nur Ziffern und die Buchstaben a bis f. Dadurch kann sie die DATABASE_URL-Verbindungszeichenfolge, in die sie eingesetzt wird, nicht beschädigen. Standard-Base64 kann einen Schrägstrich, ein Pluszeichen und ein auffüllendes Gleichheitszeichen enthalten, aber niemals ein at-Zeichen. Zeichen mit besonderer Bedeutung in einer Verbindungs-URL müssen mit Prozentkodierung maskiert werden. Das übergeordnete Prinzip wird unter Secrets aus der Compose-Datei heraushalten erläutert.
Führen Sie nun docker-compose.yml aus. Ersetzen Sie kanban.example.com an beiden Stellen durch Ihren eigenen Hostnamen.
services:
planka:
image: ghcr.io/plankanban/planka:2.2.1
restart: unless-stopped
volumes:
- planka-data:/app/data
environment:
- BASE_URL=https://kanban.example.com
- DATABASE_URL=postgresql://planka:${POSTGRES_PASSWORD}@postgres/planka
- SECRET_KEY=${SECRET_KEY}
- TRUST_PROXY=true
- DEFAULT_ADMIN_EMAIL=you@example.com
- DEFAULT_ADMIN_PASSWORD=${ADMIN_PASSWORD}
- DEFAULT_ADMIN_NAME=Your Name
- DEFAULT_ADMIN_USERNAME=admin
networks:
- proxy
- internal
labels:
- "traefik.enable=true"
- "traefik.docker.network=proxy"
- "traefik.http.routers.planka.rule=Host(`kanban.example.com`)"
- "traefik.http.routers.planka.entrypoints=websecure"
- "traefik.http.routers.planka.tls.certresolver=default"
- "traefik.http.services.planka.loadbalancer.server.port=1337"
depends_on:
postgres:
condition: service_healthy
postgres:
image: postgres:16-alpine
restart: unless-stopped
volumes:
- db-data:/var/lib/postgresql/data
environment:
- POSTGRES_DB=planka
- POSTGRES_USER=planka
- POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
networks:
- internal
healthcheck:
test: ["CMD-SHELL", "pg_isready -U planka -d planka"]
interval: 10s
timeout: 5s
retries: 5
volumes:
planka-data:
db-data:
networks:
proxy:
external: true
internal:Vier Entscheidungen in dieser Datei sind erklärungsbedürftig. Es sind die Einstellungen, die häufig geändert werden und später Probleme verursachen.
- Beim Planka-Dienst gibt es keinen
ports:-Block. Traefik erreicht den Container über dasproxy-Netzwerk. Daher wird Port 1337 niemals auf dem Host veröffentlicht. Eine Veröffentlichung würde jedem ermöglichen, den Proxy und das Zertifikat zu umgehen. loadbalancer.server.port=1337bezeichnet den Port innerhalb des Containers. Planka lauscht auf 1337. Das Upstream-Beispiel erreicht den Dienst nur über 3000, weil es den Port auf den Host abbildet. Hier gibt es keine Host-Zuordnung. Daher muss Traefik der Container-Port mitgeteilt werden.condition: service_healthywird zusammen mit dem Postgres-Healthcheck verwendet. Ohne diese Einstellung startet Planka, bevor die Datenbank Verbindungen akzeptiert. Die erste Abfrage schlägt fehl und der Prozess wird beendet. Das sieht wie eine Neustartschleife aus. Die Details werden unter Compose-Healthchecks und Startreihenfolge erläutert.- Der Datenbankdienst heißt absichtlich
postgres. Planka 2 leitet seine ausgehenden Anfragen über einen internen Filter. Dessen standardmäßige Sperrliste istlocalhost,postgres. Wenn Sie den Dienst umbenennen, entfernen Sie Ihre Datenbank unbemerkt aus dieser Liste.
Prüfen Sie, ob Compose Ihre Secrets sehen kann, bevor Sie etwas starten:
docker compose config | grep -E 'image:|BASE_URL|POSTGRES_USER'Der Befehl gibt die Datei aus. Die .env-Werte sind dabei bereits eingesetzt. Ein leerer Wert bedeutet, dass Compose die .env-Datei nicht liest. Meist führen Sie den Befehl dann aus einem anderen Verzeichnis aus.
Was die Bootstrap-Variablen für den Administrator tatsächlich bewirken
Seit Planka 1.13 wird kein Administrator mehr automatisch angelegt. Eine neue Datenbank enthält daher zunächst keinen Benutzer, der sich anmelden kann. Die Gruppe DEFAULT_ADMIN_* ist eine von zwei Möglichkeiten, das zu beheben.
Beim Start sucht Planka nach einem Benutzer, der zu DEFAULT_ADMIN_EMAIL passt. Wenn kein solcher Benutzer vorhanden ist, wird einer mit dem daneben festgelegten Passwort, Anzeigenamen und Benutzernamen angelegt. Bei späteren Starts aktualisiert Planka ein passendes Konto ebenfalls anhand dieser Variablen. Dazu gehört auch das Zurücksetzen des Passworts, solange DEFAULT_ADMIN_PASSWORD gesetzt bleibt.
DEFAULT_ADMIN_EMAIL erfüllt eine zweite Funktion, die häufig übersehen wird. Solange die Variable gesetzt ist, können der Name, die Rolle und die E-Mail-Adresse des damit bezeichneten Kontos über die Oberfläche weder geändert noch kann das Konto dort gelöscht werden. Das ist eine Sperre gegen Änderungen. Deshalb können Sie dieses Konto in der UI weder umbenennen noch seine E-Mail-Adresse ändern. Entfernen Sie die Variable und starten Sie Planka neu. Danach ist das Konto wieder ein normaler Administrator, den Sie wie jedes andere Konto bearbeiten können.
Bei der Passwortzeile ist besondere Vorsicht erforderlich. Alles unter environment: kann jeder lesen, der im Container docker inspect ausführen kann. DEFAULT_ADMIN_PASSWORD sollte dort daher nicht dauerhaft gesetzt bleiben. Melden Sie sich an, löschen Sie diese Zeile, führen Sie anschließend erneut docker compose up -d aus und ändern Sie danach Ihr Passwort in der Oberfläche.
Der sauberere Weg kommt vollständig ohne die Variablen aus. Kommentieren Sie die gesamte Gruppe DEFAULT_ADMIN_* aus und erstellen Sie das Konto anschließend interaktiv:
docker compose run --rm planka npm run db:create-admin-userDer Befehl fragt nach E-Mail-Adresse, Passwort, Anzeigenamen und optionalem Benutzernamen. Danach schreibt er den Benutzer direkt in die Datenbank. Das Passwort gelangt weder in die Compose-Datei noch in die konfigurierte Umgebung des Containers. Verwenden Sie diesen Weg, wenn mehrere Personen Shell-Zugriff auf den VPS haben. Der Befehl startet Postgres zuerst, weil depends_on verwendet wird. Deshalb funktioniert er auch bei einem Stack, der bisher noch nicht gestartet wurde.
Bei beiden Wegen müssen Sie die Planka-Passwörter manuell verwalten. Bis einschließlich Version 2.1.1 konnte die Community Edition Anmeldungen an einen OIDC-Provider wie Authentik als eigenen Single-Sign-on-Server weiterleiten. Mit Version 2.2.0, veröffentlicht im August 2026, wurden OIDC und SSO jedoch in PLANKA Pro verschoben. Die Community Edition erhielt in derselben Version die Zwei-Faktor-Authentifizierung (TOTP) für lokale Konten. Aktivieren Sie sie daher mindestens für das Administratorkonto.
Warum BASE_URL Anmeldungen verhindert, wenn sie nicht mit dem Hostnamen übereinstimmt
BASE_URL ist die genaue Adresse, die Benutzer in den Browser eingeben, einschließlich Schema und ohne abschließenden Schrägstrich. Für diesen Stack ist das https://kanban.example.com. Planka erstellt aus diesem Wert eigene Links und die Liste der zulässigen WebSocket-Ursprünge. Ein falsches BASE_URL führt deshalb nicht zu einer eindeutigen Fehlermeldung. Stattdessen wird eine Seite geladen, deren Ladevorgang nicht abgeschlossen wird.
Die häufigste Variante: Sie übernehmen das Upstream-Beispiel, lassen BASE_URL=http://localhost:3000 unverändert und rufen die Website über HTTPS unter Ihrer tatsächlichen Domain auf. Das Anmeldeformular wird abgeschickt und Ihre Zugangsdaten werden akzeptiert. Das Board wird jedoch nicht angezeigt. Öffnen Sie die Entwicklerkonsole des Browsers. Dort sehen Sie, dass Anfragen an /socket.io/ fehlschlagen, weil der Socket mit dem Ursprung der Browserseite verbunden wird, während die Ursprungseinschränkung des Servers den aus BASE_URL abgeleiteten Ursprung zulässt.
TRUST_PROXY=true ist die andere Hälfte desselben Problems. Planka läuft hinter Traefik. Deshalb erreicht jede Anfrage die Anwendung innerhalb des Docker-Netzwerks von der Adresse des Proxys über unverschlüsseltes HTTP. Ohne TRUST_PROXY ignoriert die Anwendung die von Traefik gesetzten Header X-Forwarded-Proto und X-Forwarded-For. Sie geht daher davon aus, dass die Verbindung unsicher ist, und behandelt alle Clients als eine gemeinsame IP-Adresse. Wenn der Wert gesetzt ist, liest die Anwendung diese Header aus und verwendet dasselbe Schema wie der Browser.
Traefik proxyt WebSockets ohne zusätzliche Konfiguration. Das ist ein Grund, es hier zu bevorzugen. Bei nginx muss der Proxy die Upgrade-Header proxy_set_header Upgrade $http_upgrade und proxy_set_header Connection "upgrade" weiterleiten. Andernfalls erhalten Sie denselben dauerhaft angezeigten Ladeindikator, jedoch aus einem anderen Grund. Die Header können im allgemeinen Block location / stehen. Ein separater Block für /socket.io funktioniert ebenfalls, ist aber nicht erforderlich.
Wenn Sie das Board später auf einen neuen Hostnamen verschieben, müssen Sie zwei Dinge gemeinsam ändern: den Wert BASE_URL und die Traefik-Regel Host(). Wenn Sie nur einen Wert ändern, bleibt der andere unverändert, und der Ladeindikator wird erneut dauerhaft angezeigt. Die Bereitstellung von Planka unter einem Unterpfad wie https://example.com/planka wird ab Version 2.1.0 unterstützt, die im March 2026 veröffentlicht wurde. Verwenden Sie bei älteren Tags eine eigene Subdomain.
Wo Planka Anhänge und Avatare speichert
Planka 2 speichert alle Uploads eines Benutzers unter einem einzigen Pfad im Container: /app/data. Anhänge, Benutzeravatare und Hintergrundbilder von Boards liegen dort. Version 1 verwendete drei separate Verzeichnisse. Eine aus einem älteren Beitrag übernommene Compose-Datei bindet daher Pfade ein, die nicht mehr existieren, während der vorgesehene Daten-Mount fehlt.
Dieser eine Mount entscheidet darüber, ob ein Board ein Upgrade übersteht oder danach Probleme verursacht. Das Docker-Image deklariert /app/data als Volume. Wenn der Mount in Compose fehlt, landen Uploads in einem anonymen Volume. Compose behält dieses Volume bei einer normalen up-Neuerstellung bei. Ein späteres down gefolgt von up verbindet es jedoch nicht automatisch erneut. Das Board wird scheinbar korrekt wiederhergestellt, alle Karten sind vorhanden, aber jeder Link zu einem Anhang ist ungültig, weil die Datenbankeinträge weiterhin auf Dateien im alten Volume verweisen.
Das benannte Volume in der obigen Compose-Datei verhindert dieses Problem. Ein Bind-Mount funktioniert ebenfalls und erleichtert die Sicherung der Dateien mit herkömmlichen Werkzeugen. Dafür ist ein zusätzlicher Schritt erforderlich. Der Node-Prozess im Container läuft mit UID 1000. Ein Host-Verzeichnis, das root gehört, führt beim ersten Upload zu einem Berechtigungsfehler:
sudo chown -R 1000:1000 /opt/planka/dataDer Unterschied zwischen beiden Varianten wird in Bind-Mounts im Vergleich zu benannten Volumes erläutert.
Wenn die Anhänge den Speicherplatz Ihres Tarifs überschreiten, kann Planka sie stattdessen über S3_ENDPOINT, S3_BUCKET und die zugehörigen Schlüsselvariablen in einem S3-kompatiblen Speicher ablegen. Das kann auf einen gehosteten Bucket oder auf einen selbst gehosteten MinIO-Objektspeicher auf einem anderen Server verweisen. Entscheiden Sie dies, bevor das Team das Board mit Inhalten füllt. Durch die Aktivierung von S3 werden Lese- und Schreibvorgänge für Dateien auf dieses Backend umgestellt, ohne vorhandene Uploads zu migrieren.
Stack starten und prüfen, ob er funktioniert
docker compose pull
docker compose up -d
docker compose psdocker compose ps sollte postgres als healthy und planka als running anzeigen. Wenn Planka in einer Neustartschleife läuft, sollten Sie zuerst die Datenbankverbindung prüfen, nicht die Anwendung.
docker compose logs -f plankaBeim ersten erfolgreichen Start werden die Datenbankmigrationen ausgeführt. Die Produktionskonfiguration setzt jedoch noShip: true und unterdrückt die Startmeldung, die Port 1337 meldet. Prüfen Sie das Schema direkt über Postgres, statt dem Log zu vertrauen:
docker compose exec postgres psql -U planka -d planka -c '\dt'Eine Tabellenliste mit board und card zeigt, dass die Migrationen ausgeführt wurden. "Did not find any relations" bedeutet, dass Planka keine Verbindung hergestellt hat. Vergleichen Sie daher DATABASE_URL mit den Werten POSTGRES_USER und POSTGRES_PASSWORD in Ihrer .env.
Prüfen Sie anschließend die Route von Ihrem eigenen Rechner aus, nicht vom VPS:
curl -I https://kanban.example.comHTTP/2 200 bedeutet, dass Traefik ein Zertifikat verwaltet und den Container erreicht. Ein von Traefik gelieferter 404-Fehler bedeutet, dass kein Router zur Anfrage passt: Die Host()-Regel passt nicht zum angeforderten Hostnamen, oder Traefik hat die Labels nicht übernommen. Ein 502-Fehler bedeutet, dass der Router zwar passte, Traefik den Container aber nicht erreichen konnte, beispielsweise weil er nicht mit dem proxy-Netzwerk verbunden ist. Öffnen Sie nun die Website und melden Sie sich mit dem Administratorkonto an.
Vor jedem Versionssprung einen pg_dump erstellen
Ihre Board-Daten liegen in zwei getrennten Speichern. Eine Sicherung muss daher beide abdecken: die Postgres-Datenbank und das planka-data-Volume. Erstellen Sie den Dump, während der Stack läuft.
docker compose exec -T postgres pg_dump -U planka -d planka > "planka-db-$(date +%F).sql"-T deaktiviert die standardmäßige Pseudo-Terminal-Zuweisung von Compose. Dadurch bleibt der Dump ein einfacher Ausgabestream.
Anschließend sichern Sie die Uploads. Ermitteln Sie zuerst den tatsächlichen Volume-Namen, da Compose den Namen des Projektverzeichnisses voranstellt.
docker volume ls | grep planka
docker run --rm -v planka_planka-data:/data -v "$PWD":/backup alpine \
tar czf /backup/planka-files-$(date +%F).tgz -C /data .Das Projekt enthält außerdem docker-backup.sh und docker-restore.sh in seinem Repository. Die offizielle Dokumentation sieht dafür einen nächtlichen Cron-Job vor. Beide Ansätze sind geeignet. Nicht geeignet ist jedoch eine Sicherung, die Sie nie wiederhergestellt haben. Stellen Sie eine Sicherung daher einmal auf einem Test-VPS wieder her. Prüfen Sie anschließend, ob Sie sich anmelden und einen Anhang öffnen können. Dasselbe Speicherpaar findet sich in jeder Compose-Anwendung, die Uploads akzeptiert. Wenn Sie später Chatwoot auf demselben Server wie Ihren Support-Desk betreiben, können Sie die hier erstellte Routine mit nur geringfügig angepassten Volume-Namen übernehmen.
Führen Sie den Dump unmittelbar vor jeder Versionsänderung aus. Eine Sicherung von letzter Nacht ist nicht dasselbe wie eine Sicherung unmittelbar vor der Migration, die Sie jetzt ausführen werden.
Tags festlegen und Release Notes lesen
Beide Image-Tags in dieser Datei sind absichtlich festgelegt.
ghcr.io/plankanban/planka:2.2.1 bezeichnet ein bestimmtes Release, das im Oktober 2026 aktuell ist. Community 2.3.0 wurde am 4. November 2026 mit Sicherheitskorrekturen veröffentlicht, und das Upstream-Projekt empfiehlt ein Update. Community 2.3.1 folgte am 5. November 2026. Diese Version behebt einen Absturz beim Bearbeiten von Kartenbeschreibungen auf Boards mit einem Mitglied ohne Benutzernamen. latest ändert sich bei jeder Veröffentlichung des Upstream-Projekts. Ein routinemäßiges docker compose pull kann dadurch zu einem Zeitpunkt eine Schema-Migration einspielen, den Sie nicht gewählt haben. Lesen Sie die Release Notes, bevor Sie diese Nummer ändern. Dort werden inkompatible Änderungen und Sicherheitskorrekturen beschrieben. Version 2.0.3 wurde als Security Release veröffentlicht. Genau solche Änderungen sollten Sie bewusst lesen und nicht zufällig übernehmen. Das gilt auch für 2.2.1, das im August 2026 veröffentlicht wurde. Diese Version behebt eine Path-Traversal-Schwachstelle, über die ein angemeldeter Benutzer beliebige Dateien auf Instanzen mit lokalem Dateispeicher lesen konnte. Das ist die Konfiguration in dieser Anleitung. Im Advisory werden 2.1.1 und frühere Versionen als betroffen aufgeführt. Wenn Sie von 2.1.x kommen, lesen Sie zuerst die Notes zu 2.2.0. Dieses Release deaktiviert Benutzer, die sich bisher ausschließlich über SSO angemeldet haben, bis ein Administrator ihnen ein Passwort zuweist und sie wieder aktiviert. Das Festlegen von Versionen ist hier einfach, weil das Upstream-Projekt überhaupt Images veröffentlicht. Wenn ein Projekt keine Images bereitstellt, müssen Sie dieselbe Disziplin mit einem zusätzlichen Schritt anwenden, wie bei openGym, das auf dem Rechner aus einem ausgecheckten git-Tag erstellt wurde.
postgres:16-alpine ist aus einem wichtigeren Grund auf eine Major-Version festgelegt. Postgres schreibt sein Datenverzeichnis in einem Format, das an die Major-Version gebunden ist. Der Server verweigert das Öffnen eines Verzeichnisses, das mit einer anderen Version geschrieben wurde. Wenn Sie postgres:latest eintragen und der Tag über 16 hinausgeht, startet der Container nicht. Das Image für 17 beendet sich beispielsweise mit:
FATAL: database files are incompatible with server
DETAIL: The data directory was initialized by PostgreSQL version 16, which is not compatible with this version 17.Es gehen keine Daten verloren. Auch ein Neustart behebt das Problem nicht. Der Wechsel zu einer neuen Postgres-Major-Version erfordert einen Dump mit der alten Version und eine Wiederherstellung in einem frischen Datenverzeichnis der neuen Version, einen pg_upgrade-Lauf, der die Daten ohne Dump konvertiert, aber gleichzeitig verfügbare Binärdateien des alten und neuen Servers benötigt, oder eine logische Replikation auf einen Server mit der neuen Version und anschließend einen Switchover. Jede dieser Varianten ist eine geplante Migration und keine Nebenwirkung eines Image-Pulls. Bei der logischen Replikation kann der alte Server weiterlaufen, während der neue Server aufholt.
Wenn Sie eine vorhandene Planka-1.x-Installation aktualisieren und nicht neu beginnen, hat dieses Upgrade ein eigenes dokumentiertes Verfahren in der Projektdokumentation. Ohne vorher erstelltes Backup gibt es keinen Weg zurück zu Version 1.
Fehlerbilder und die angezeigten Zeichenfolgen
Planka wird wiederholt neu gestartet, und im Log wird die Datenbank genannt. Die Zugangsdaten in DATABASE_URL stimmen nicht mit der Postgres-Umgebung überein. Beachten Sie, dass POSTGRES_PASSWORD nur bei der ersten Initialisierung des Datenverzeichnisses angewendet wird. Wenn Sie die Variable nach einem fehlerhaften ersten Start korrigieren, ändert das daher nichts. Ändern Sie das Passwort der Datenbankrolle mit ALTER ROLE so, dass es mit dem konfigurierten Passwort übereinstimmt. Das Entfernen des db-data-Volumes ist nur bei einer kurzlebigen Installation ohne zu erhaltende Daten eine Option.
Die Anmeldung ist erfolgreich, aber das Board wird nicht geladen. BASE_URL stimmt nicht mit der Adresse in der Browserzeile überein. Deshalb weist der Server den Origin des Sockets zurück. Die Browserkonsole zeigt fehlgeschlagene Anfragen an /socket.io/.
Uploads schlagen fehl, während alles andere funktioniert. Ein Bind-Mount gehört root. Führen Sie sudo chown -R 1000:1000 für das Verzeichnis auf dem Host aus und starten Sie den Container neu.
Anhänge sind nach einem Upgrade verschwunden. /app/data war nicht mit dem ursprünglichen Upload-Volume verbunden. Verbinden Sie dieses Volume erneut oder stellen Sie die Dateien aus einem Backup wieder her. Verwenden Sie anschließend ein benanntes Volume, bevor Sie den Image-Tag erneut ändern.
Traefik gibt 404 zurück. Kein Router hat die Anfrage zugeordnet. Die Host()-Regel stimmt nicht mit Ihrem DNS-Eintrag überein, oder die Labels wurden nie an Traefik übergeben. docker compose config zeigt die Labels nach der Ersetzung. Dort werden Tippfehler sichtbar. Ein 502 bedeutet dagegen, dass die Route gefunden wurde, der Container jedoch nicht erreichbar war. Prüfen Sie daher, ob er sich im proxy-Netzwerk befindet.
Benachrichtigungen oder Webhooks kommen nie an. Planka 2 sendet seine ausgehenden HTTP-Anfragen über einen internen Filter. Die standardmäßige Blockliste umfasst localhost und postgres. Ein auf localhost gerichteter Webhook wird absichtlich blockiert. Sobald Sie OUTGOING_ALLOWED_HOSTS festlegen, wird außerdem jeder Host blockiert, der nicht in dieser Liste steht. Richten Sie den Webhook auf den Servicenamen des anderen Containers und fügen Sie diesen Namen bei Verwendung einer Allowlist zu OUTGOING_ALLOWED_HOSTS hinzu, anstatt den Filter zu entfernen.
Sobald der Stack läuft, ist der Betriebsaufwand gering. Lesen Sie die Release Notes, und sichern Sie die Datenbank vor jedem Upgrade. Nach einem Reboot wird der Stack aufgrund von restart: unless-stopped automatisch wieder gestartet, sofern der Docker-Dienst selbst beim Booten aktiviert ist. Compose-Stacks, die nach einem Reboot wieder gestartet werden behandelt die Fälle, in denen dies nicht geschieht.
FAQ
Warum lädt Planka nach der Anmeldung dauerhaft?
Die Zugangsdaten wurden akzeptiert, aber die Live-Verbindung nicht. Der Browser öffnet seinen Socket zum Ursprung der Seite. Planka leitet die zulässigen Socket-Ursprünge aus BASE_URL ab. Wenn diese Variable auf http://localhost:3000 gesetzt bleibt, während Sie die Website unter https://kanban.example.com aufrufen, weist der Server die Verbindung zurück. Die Entwicklerkonsole zeigt fehlgeschlagene Anfragen an /socket.io/. Setzen Sie BASE_URL auf die exakte öffentliche Adresse ohne abschließenden Schrägstrich. Fügen Sie TRUST_PROXY=true hinzu, damit die Anwendung den X-Forwarded-Proto-Header Ihres Reverse Proxy berücksichtigt. Führen Sie anschließend docker compose up -d aus.
Wie erstelle ich den ersten Planka-Administratorkonto?
Seit Version 1.13 wird kein Administrator automatisch erstellt. Setzen Sie entweder DEFAULT_ADMIN_EMAIL mit den zugehörigen Variablen für Passwort, Namen und Benutzernamen und starten Sie den Stack, oder führen Sie docker compose run --rm planka npm run db:create-admin-user aus und beantworten Sie die Eingabeaufforderungen. Der interaktive Befehl ist auf einem gemeinsam genutzten Server sicherer, weil das Passwort nicht in die konfigurierte Umgebung des Containers gelangt, in der docker inspect es lesen kann. Wenn DEFAULT_ADMIN_EMAIL anschließend gesetzt bleibt, verhindert dies Änderungen an Name, Rolle und E-Mail-Adresse dieses Kontos sowie dessen Löschung über die Benutzeroberfläche. Entfernen Sie DEFAULT_ADMIN_PASSWORD nach der Einrichtung, weil das passende Kontopasswort bei jedem Start zurückgesetzt wird, solange die Variable gesetzt ist.
Wo speichert Planka Anhänge und Avatare?
Alle hochgeladenen Dateien liegen unter /app/data im Container von Planka 2. Dazu gehören Anhänge, Benutzeravatare und Board-Hintergründe. Binden Sie diesen Pfad in ein benanntes Volume ein. Ohne eine explizite Einbindung verwendet das Docker-Image ein anonymes Volume. Ein nachfolgendes docker compose up verbindet dieses Volume nach docker compose down nicht automatisch erneut. Eine Bind-Mount-Einbindung funktioniert ebenfalls. Der Node-Prozess läuft jedoch mit UID 1000. Führen Sie daher sudo chown -R 1000:1000 für das Verzeichnis auf dem Host aus. Andernfalls schlagen Uploads mit einem Berechtigungsfehler fehl.
Wie viel RAM benötigt ein selbst gehostetes Planka?
Die technische FAQ des Projekts empfiehlt für kleine Teams mindestens 2 GB RAM und 10 GB Speicherplatz. Die standardmäßige Docker-Bereitstellung führt einen Node-Prozess, einen Postgres-Server mit einem Backend-Prozess pro offener Verbindung und einen internen Squid-Proxy zur Filterung ausgehender Anfragen aus. Führen Sie docker stats --no-stream nach einer normalen Woche aus und dimensionieren Sie anhand Ihrer eigenen Werte. Überwachen Sie den Speicherplatz genauer als den Arbeitsspeicher, weil die Anhänge wachsen.
Wie aktualisiere ich Planka ohne Datenverlust?
Sichern Sie die Datenbank und archivieren Sie das Uploads-Volume unmittelbar vor dem Upgrade. Verwenden Sie dafür nicht den Zeitplan der Sicherung aus der vergangenen Nacht. Verwenden Sie docker compose exec -T postgres pg_dump -U planka -d planka > planka-db.sql und behalten Sie -T bei, um die Pseudo-Terminal-Zuweisung für die umgeleitete Ausgabe zu deaktivieren. Lesen Sie die Release Notes für jede übersprungene Version. Ändern Sie das Image-Tag auf ein bestimmtes Release statt auf latest. Führen Sie anschließend docker compose pull und docker compose up -d aus und überwachen Sie das Log auf die Migration. Lassen Sie das Postgres-Tag auf die jeweilige Major-Version festgelegt. Der Server verweigert den Zugriff auf ein Datenverzeichnis, das von einer anderen Major-Version geschrieben wurde.