Kanboard mit Docker Compose selbst hosten: Kanban-Board mit Backup und Restore

Kanboard ist ein schlankes Kanban-Werkzeug für Teams, die Aufgaben sichtbar machen wollen, ohne gleich eine große Projektmanagement-Suite zu betreiben. Die Anwendung ist in PHP geschrieben, steht unter MIT-Lizenz und speichert im Standardfall alles in einer einzigen SQLite-Datei. Das macht sie für kleine IT-Abteilungen, Agenturen und Handwerksbetriebe interessant: Ein Container, ein Volume, ein Backup. Diese Anleitung zeigt die Installation mit Docker Compose, die sichere Erstkonfiguration, den Betrieb mit API, ein Backup mit echtem Restore, das Update auf eine neue Version und die typischen Fehlerbilder. Alle Befehle und Ausgaben stammen aus einem Testlauf mit Kanboard v1.2.53 und dem Update auf v1.2.54.

Voraussetzungen

Kanboard ist genügsam. Im Test belegte der Container nach dem Start rund 29 MB Arbeitsspeicher, das Image v1.2.54 ist 136 MB groß. Planen Sie trotzdem Reserven für Betriebssystem, Backups und weitere Dienste ein.

• Linux-Server oder VM mit x86_64 oder ARM64, mindestens 1 CPU-Kern und 1 GB RAM, für ein Team bis etwa 30 Personen reichen 2 Kerne und 2 GB RAM
• 5 GB freier Speicher für Image, Datenbank und Dateianhänge, bei vielen Anhängen entsprechend mehr
• Docker Engine mit Compose-Plugin (Befehl docker compose)
• ein freier TCP-Port, in dieser Anleitung 8080
• für den Zugriff von außen ein Reverse Proxy mit HTTPS oder ein VPN, Kanboard selbst sollte nicht direkt im Internet stehen
• optional ein SMTP-Konto für Benachrichtigungen, denn das Image unterstützt die Transporte mail und sendmail nicht

Eckdaten

Eigenschaft	Wert
Image	kanboard/kanboard:v1.2.54 (auch ghcr.io und quay.io)
Port im Container	80 (HTTP), 443 mit selbst signiertem Zertifikat
Volumes	/var/www/app/data (SQLite, Anhänge, config.php), /var/www/app/plugins
Wichtige Variablen	PLUGIN_INSTALLER, DATABASE_URL, TZ
Healthcheck	/healthcheck.php, im Image bereits hinterlegt
Lizenz	MIT

Schritt 1: Projektordner und Compose-Datei anlegen

Die offizielle Beispieldatei docker-compose.sqlite.yml im Repository nutzt latest, einen festen Containernamen und veröffentlicht die Ports 80 und 443. Für den Dauerbetrieb ist eine feste Version besser, weil Sie dann selbst entscheiden, wann ein Update kommt. Die Kanboard-Dokumentation empfiehlt das ausdrücklich. Legen Sie einen Ordner an:

mkdir -p /opt/kanboard && cd /opt/kanboard

Die Datei .env enthält nur die Version:

KB_TAG=v1.2.54

Die Datei compose.yaml:

services:
  app:
    image: kanboard/kanboard:${KB_TAG:-v1.2.54}
    restart: unless-stopped
    ports:
      - "8080:80"
    volumes:
      - data:/var/www/app/data
      - plugins:/var/www/app/plugins
    environment:
      PLUGIN_INSTALLER: "false"
      TZ: Europe/Berlin

volumes:
  data:
  plugins:

Das Volume für die Zertifikate unter /etc/nginx/ssl fehlt bewusst. Hinter einem Reverse Proxy brauchen Sie das selbst signierte Zertifikat des Containers nicht. PLUGIN_INSTALLER bleibt auf false: Plugins aus der Weboberfläche zu installieren, bedeutet fremden PHP-Code ohne Prüfung auf Ihrem Server.

Verifizieren: docker compose config gibt die Konfiguration ohne Fehlermeldung aus und zeigt als Image kanboard/kanboard:v1.2.54.

Schritt 2: Kanboard starten

docker compose up -d
docker compose ps

Beim ersten Start erzeugt der Einstiegspunkt ein selbst signiertes Zertifikat, setzt die Rechte auf das Datenvolume und legt die Datenbank an. Danach startet s6 die Dienste nginx, PHP-FPM und cron. Der Cronjob für tägliche Aufgaben wie Statistiken und Benachrichtigungen ist im Image bereits eingerichtet, Sie müssen dafür nichts tun.

$ curl -s localhost:8080/healthcheck.php
{"status":200,"message":"Database connection is OK"}
$ docker compose exec app php /var/www/app/cli version
v1.2.54

Verifizieren: docker compose ps zeigt den Status Up (healthy), der Healthcheck antwortet mit "status":200. Im Browser erscheint unter http://SERVER:8080 die Anmeldeseite.

Schritt 3: Standardkennwort sofort ändern

Jede neue Kanboard-Instanz hat den Benutzer admin mit dem Kennwort admin. Ändern Sie es, bevor die Instanz für andere erreichbar ist. Am sichersten geht das über die Kommandozeile im Container, dann taucht das Kennwort weder in einem Browserverlauf noch in einem Proxy-Log auf:

$ docker compose exec app php /var/www/app/cli user:reset-password admin
What is the new password for admin? (characters are not printed)
Confirmation:
Password updated successfully

Den Erfolg prüfen Sie über die JSON-RPC-API. Das alte Kennwort muss abgewiesen werden:

$ curl -s -u admin:admin -d '{"jsonrpc":"2.0","method":"getVersion","id":1}' \
    http://localhost:8080/jsonrpc.php
{"jsonrpc":"2.0","error":{"code":401,"message":"Unauthorized"},"id":null}

Mit dem neuen Kennwort liefert derselbe Aufruf die Versionsnummer. Legen Sie für jede Person ein eigenes Konto an. Kanboard bietet pro Benutzer Zwei-Faktor-Authentifizierung per TOTP, die Sie unter Mein Profil aktivieren.

Verifizieren: Die API antwortet für admin:admin mit HTTP 401, eine Anmeldung mit dem neuen Kennwort leitet auf /dashboard weiter.

Schritt 4: Anwendung konfigurieren

Unter Einstellungen, Anwendungskonfiguration tragen Sie die Applikations-URL ein, also die Adresse, unter der Ihre Mitarbeiter Kanboard erreichen. Sie wird für Links in E-Mails und Feeds verwendet. Stellen Sie außerdem Sprache, Zeitzone und Datumsformat um. Kanboard bringt eine förmliche und eine informelle deutsche Übersetzung mit; für Firmen passt meist „Deutsch (Sie)“.

Spalten, Farben und Swimlanes legen Sie pro Projekt fest. Neue Projekte starten mit Backlog, Ready, Work in progress und Done. Im Test wurden die Spalten in Offen, Bereit, In Arbeit und Erledigt umbenannt, was sich über die Projekteinstellungen oder per API erledigen lässt. Ein Spaltenlimit (WIP-Limit) verhindert, dass zu viele Aufgaben gleichzeitig in Arbeit sind.

Für E-Mail-Benachrichtigungen hinterlegen Sie SMTP-Zugangsdaten in einer eigenen config.php im Datenvolume unter /var/www/app/data/config.php oder als Umgebungsvariablen in der Compose-Datei. Nach einer Änderung an der Datei starten Sie den Container neu.

Verifizieren: Nach dem Speichern bestätigt Kanboard die Änderung oben auf der Seite, beim nächsten Seitenaufruf ist die Oberfläche deutsch und die Vorschau des Datumsformats zeigt 17.10.2026.

Schritt 5: API für Automatisierung nutzen

Kanboard hat eine JSON-RPC-API unter /jsonrpc.php. Es gibt zwei Arten der Anmeldung: den Anwendungszugang mit dem Benutzernamen jsonrpc und dem globalen API-Token aus Einstellungen, API, sowie persönliche Zugänge mit Benutzername und Kennwort oder persönlichem Zugriffstoken. Das globale Token hat volle Rechte, behandeln Sie es wie ein Administratorkennwort. Benutzer mit aktivierter Zwei-Faktor-Authentifizierung müssen ein persönliches Token verwenden.

$ curl -s -u "jsonrpc:$KB_TOKEN" \
    -d '{"jsonrpc":"2.0","method":"createProject","id":1,"params":{"name":"IT-Betrieb"}}' \
    http://localhost:8080/jsonrpc.php
{"jsonrpc":"2.0","result":2,"id":1}

Ein falsches Token beantwortet Kanboard mit HTTP 401 und Unauthorized. Achtung bei Aufgaben über den Anwendungszugang: createTask mit owner_id lieferte im Test "result":false, solange der Benutzer nicht Mitglied des Projekts war. Erst nach addProjectUser mit der Rolle project-manager klappte die Zuweisung. Ohne owner_id wird die Aufgabe sofort angelegt.

Verifizieren: getVersion mit dem richtigen Token liefert "result":"v1.2.54", mit falschem Token HTTP 401.

Schritt 6: Backup erstellen

Alle Projekte, Aufgaben, Benutzer und Einstellungen liegen in db.sqlite im Datenvolume, Anhänge im Unterordner files desselben Volumes. Das Image enthält kein sqlite3, und seit v1.2.27 arbeitet die Datenbank im WAL-Modus. Kopieren Sie die Datei deshalb nicht im laufenden Betrieb, sondern stoppen Sie den Container für wenige Sekunden und sichern Sie das komplette Volume mit einem Hilfscontainer:

mkdir -p backup
docker compose stop app
docker run --rm -v kanboard_data:/data:ro -v "$PWD/backup":/backup alpine \
  tar czf /backup/kanboard-data-$(date +%F).tar.gz -C /data .
docker compose start app

Der Volumename setzt sich aus dem Projektnamen, also dem Ordnernamen, und dem Volume zusammen. Aus /opt/kanboard wird kanboard_data; docker volume ls zeigt den tatsächlichen Namen. Sichern Sie das Plugin-Volume auf demselben Weg, falls Sie Plugins nutzen. Kopieren Sie das Archiv anschließend auf ein anderes System, etwa mit einem Backup-Werkzeug wie restic.

Zusätzlich bietet Kanboard unter Einstellungen, Über einen Download der Datenbank als db.sqlite.gz. Das ersetzt kein automatisiertes Backup und enthält keine Anhänge.

Verifizieren: tar tzf backup/kanboard-data-*.tar.gz listet mindestens ./db.sqlite. Im Test war das Archiv mit zwei Projekten knapp 10 KB groß.

Schritt 7: Restore durchführen und prüfen

Ein Backup ist erst etwas wert, wenn der Restore funktioniert. Im Test wurde vor der Sicherung ein Projekt „Marker Restore-Test“ mit der Aufgabe „MARKER-4711 Restore-Prüfung“ angelegt. Nach dem Backup wurde das Projekt gelöscht und anschließend das komplette Datenvolume entfernt, also ein Totalverlust simuliert:

docker compose down
docker volume rm kanboard_data
docker compose up -d

Kanboard startete daraufhin als leere Neuinstallation: getAllProjects lieferte eine leere Liste, und das Standardkennwort admin war wieder gültig. Zurückgespielt wird so:

docker compose stop app
docker run --rm -v kanboard_data:/data -v "$PWD/backup":/backup:ro alpine \
  sh -c "rm -rf /data/* && tar xzf /backup/kanboard-data-2026-10-17.tar.gz -C /data"
docker compose start app

Die Dateirechte müssen Sie nicht anpassen: Der Einstiegspunkt des Images setzt bei jedem Start chown nginx:nginx auf das Datenverzeichnis. Nach dem Start war das alte Kennwort wieder aktiv, admin:admin wurde mit HTTP 401 abgewiesen, und beide Projekte samt Marker-Aufgabe waren vorhanden. Eine neue Aufgabe „Schreibtest nach Restore“ ließ sich anlegen, die Datenbank ist also beschreibbar.

Verifizieren: Der Healthcheck meldet Database connection is OK, die Anmeldung mit dem alten Standardkennwort scheitert, und die vor dem Backup angelegten Projekte sind in der Projektliste sichtbar.

Schritt 8: Kanboard aktualisieren

Lesen Sie vor jedem Update das ChangeLog im Repository und erstellen Sie ein Backup nach Schritt 6. Dann tragen Sie die neue Version in .env ein und erstellen den Container neu:

sed -i 's/KB_TAG=v1.2.53/KB_TAG=v1.2.54/' .env
docker compose pull
docker compose up -d

Im Test lief das Update von v1.2.53 auf v1.2.54 ohne Eingriff. Kanboard prüft das Datenbankschema bei jedem Aufruf und führt fehlende Migrationen automatisch aus. Danach meldete cli version v1.2.54, cli db:version zeigte Schema 128, und die Marker-Aufgabe war weiterhin vorhanden. Bei größeren Sprüngen oder mehreren Instanzen auf einer Datenbank empfiehlt die Dokumentation, die automatische Migration mit DB_RUN_MIGRATIONS abzuschalten und cli db:migrate gezielt auszuführen.

Verifizieren: docker compose ps zeigt das neue Image mit healthy, docker compose exec app php /var/www/app/cli version gibt die neue Version aus, und Ihre Projekte sind unverändert.

Troubleshooting

Port bereits belegt

Läuft auf dem Host schon ein Dienst auf dem Port, bricht der Start ab mit Bind for 0.0.0.0:8080 failed: port is already allocated. Ändern Sie die linke Seite der Portzuordnung, etwa auf "8081:80", oder beenden Sie den anderen Dienst.

Anmeldung schlägt fehl

Ein falsches Kennwort quittiert die Anmeldeseite mit „Bad username or password“ bzw. der deutschen Entsprechung. Im Log steht dann Kanboard: user admin authentication failure with IP address: 172.18.0.1. Die IP ist das Docker-Gateway, nicht der echte Client. Für fail2ban oder Rate-Limits gehört die Absicherung deshalb in den Reverse Proxy. Nach drei Fehlversuchen zeigt Kanboard ein CAPTCHA, nach sechs ist das Konto 15 Minuten gesperrt. Ein Administrator entsperrt es im Benutzerprofil.

Kennwort vergessen

Setzen Sie es mit docker compose exec app php /var/www/app/cli user:reset-password BENUTZER neu. Hat das Konto Zwei-Faktor-Authentifizierung und ist das Gerät verloren, hilft cli user:reset-2fa BENUTZER.

Keine E-Mails

Das offizielle Image kann weder mail noch sendmail verwenden. Stellen Sie auf SMTP um und prüfen Sie Host, Port und Verschlüsselung in Ihrer config.php.

Container meldet unhealthy

Der Healthcheck prüft die Datenbankverbindung. Antwortet /healthcheck.php mit 503, ist meist die Datenbank nicht lesbar oder nicht erreichbar. Prüfen Sie mit docker compose logs app die Fehlermeldung und kontrollieren Sie bei externer Datenbank DATABASE_URL.

Häufige Fragen

Reicht SQLite oder brauche ich PostgreSQL oder MariaDB?

Für kleine und mittlere Teams reicht SQLite, und das Backup bleibt ein einzelnes Archiv. Das Repository enthält Beispieldateien für MariaDB und PostgreSQL, die Sie über DATABASE_URL anbinden. Das lohnt sich bei vielen gleichzeitigen Nutzern.

Kann ich Kanboard direkt ins Internet stellen?

Die Kanboard-Dokumentation rät davon ab. Setzen Sie einen Reverse Proxy mit HTTPS und Rate-Limit davor oder erlauben Sie den Zugriff nur über VPN. Der Proxy muss eingehende X-Forwarded-Header überschreiben.

Wie installiere ich Plugins?

Ohne Web-Installer laden Sie das Plugin als Zip herunter und nutzen cli plugin:install URL oder entpacken es in das Plugin-Volume. Prüfen Sie die Herkunft, denn Plugins werden nicht begutachtet.

Gibt es einen Restore über die Weboberfläche?

Nein. Die Oberfläche bietet nur den Download der Datenbank. Der Restore läuft immer über das Zurückspielen der Datei bei gestopptem Container, wie in Schritt 7.

Fazit

Kanboard ist schnell eingerichtet und bleibt im Betrieb pflegeleicht: ein Container, ein Datenvolume, automatische Migrationen. Die wichtigsten Handgriffe sind das sofortige Ändern des Standardkennworts, eine fest eingetragene Version und ein regelmäßiges Volume-Backup, dessen Restore Sie mindestens einmal ausprobieren. Wer mehr als Kanban braucht, etwa Zeiterfassung mit Rechnungsstellung oder Gantt-Planung für viele Projekte, sollte Alternativen wie Leantime ansehen.

Weiterführende Anleitungen und Quellen

• Leantime mit Docker Compose: Projektmanagement selbst hosten
• Backrest: restic-Backups mit Weboberfläche
• YAML-Validator: Fehler in Compose-Dateien finden
• Kanboard Dokumentation: Docker Image Usage
• Kanboard Dokumentation: SQLite, Export und Import
• Kanboard Dokumentation: Upgrading to a New Version
• Kanboard Dokumentation: Security
• Kanboard Dokumentation: API Authentication
• Kanboard auf GitHub
• kanboard/kanboard auf Docker Hub