Vikunja als Aufgabenverwaltung mit Docker installieren¶

Veröffentlicht am 7. August 2026 · Geschätzte Lesezeit: 5 Minuten

Vikunja verwaltet persönliche Aufgaben und gemeinsame Projekte in Listen, Tabellen oder Kanban-Boards. Anwendung, Anhänge und PostgreSQL-Datenbank laufen auf deinem eigenen Server. Für Installation und ersten Funktionstest brauchst du ungefähr 25 bis 35 Minuten.

Voraussetzungen

Ein Linux-Server mit Docker und Docker Compose
Eine feste IP-Adresse oder DHCP-Reservierung für den Server
Port 3456 im lokalen Netz frei
openssl und ein Benutzer mit sudo-Rechten

1. Arbeitsordner anlegen¶

Erstelle Ordner für Compose-Datei, Anhänge, Datenbank und Sicherungen:

sudo mkdir -p /opt/vikunja/files /opt/vikunja/db /opt/vikunja/backup

Vikunja läuft im Container standardmäßig mit der Benutzer-ID 1000. Gib ihm Schreibrechte auf den Anhangsordner:

sudo chown -R 1000:1000 /opt/vikunja/files

Übergib die übrigen Arbeitsdateien deinem Linux-Benutzer. Ersetze <benutzer> durch deinen Benutzernamen:

sudo chown <benutzer>:<benutzer> /opt/vikunja /opt/vikunja/backup

Wechsle in den Arbeitsordner:

cd /opt/vikunja

2. Zufällige Geheimnisse erzeugen¶

Der folgende Befehl erzeugt ein Datenbankpasswort und einen separaten geheimen Anwendungsschlüssel. Beide werden direkt in die Datei .env geschrieben und nicht auf dem Bildschirm angezeigt:

printf 'VIKUNJA_DB_PASSWORD=%s\nVIKUNJA_SERVICE_SECRET=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env

Schütze die Datei vor anderen lokalen Benutzern:

chmod 600 .env

Prüfe nur die Namen der beiden gesetzten Variablen:

cut -d= -f1 .env

Datei nicht veröffentlichen

.env enthält das Datenbankpasswort und den Signaturschlüssel. Veröffentliche sie niemals und nimm sie nur verschlüsselt in deine Sicherung auf.

3. Compose-Datei erstellen¶

Lege unter /opt/vikunja die Datei compose.yaml mit folgendem Inhalt an. Ersetze <server-ip> durch die feste IP-Adresse deines Servers, zum Beispiel 192.168.178.20:

services:
  vikunja:
    image: vikunja/vikunja:latest
    container_name: vikunja
    restart: unless-stopped
    environment:
      VIKUNJA_SERVICE_PUBLICURL: http://<server-ip>:3456/
      VIKUNJA_SERVICE_SECRET: ${VIKUNJA_SERVICE_SECRET}
      VIKUNJA_DATABASE_HOST: db
      VIKUNJA_DATABASE_PASSWORD: ${VIKUNJA_DB_PASSWORD}
      VIKUNJA_DATABASE_TYPE: postgres
      VIKUNJA_DATABASE_USER: vikunja
      VIKUNJA_DATABASE_DATABASE: vikunja
    ports:
      - "<server-ip>:3456:3456"
    volumes:
      - ./files:/app/vikunja/files
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:18
    container_name: vikunja-db
    restart: unless-stopped
    environment:
      POSTGRES_PASSWORD: ${VIKUNJA_DB_PASSWORD}
      POSTGRES_USER: vikunja
      POSTGRES_DB: vikunja
    volumes:
      - ./db:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h localhost -U $$POSTGRES_USER"]
      interval: 2s
      start_period: 30s

Die Datenbank ist nicht nach außen freigegeben. Der Eintrag VIKUNJA_SERVICE_PUBLICURL muss genau zu der Adresse passen, die du im Browser verwendest; sonst kann die Registrierung mit unauthorized scheitern.

4. Container starten¶

Starte Vikunja und PostgreSQL im Hintergrund:

docker compose up -d

Prüfe, ob die Datenbank gesund und Vikunja gestartet ist:

docker compose ps

Bei Problemen zeigen die Protokolle die Ursache:

docker compose logs --tail=100 vikunja db

Keine Shell im Vikunja-Container

Das offizielle Vikunja-Image enthält keine interaktive Shell. Ein Befehl wie docker exec -it vikunja sh funktioniert deshalb nicht. Verwende zur Fehlersuche docker compose logs.

5. Konto und erstes Projekt anlegen¶

Öffne die Oberfläche im Browser:

http://<server-ip>:3456

Ersetze <server-ip> durch die Adresse aus der Compose-Datei. Registriere das erste Konto mit einem langen, einzigartigen Passwort. Lege anschließend ein Projekt namens Test und darin eine Aufgabe mit Fälligkeitsdatum an.

Zugriff aus dem Internet absichern

Leite Port 3456 nicht unverschlüsselt im Router weiter. Nutze außerhalb des Heimnetzes ein VPN oder einen HTTPS-Reverse-Proxy. Aktiviere bei öffentlich erreichbaren Installationen nach dem Anlegen aller Konten zusätzlich eine passende Registrierungsbeschränkung.

6. API-Funktion prüfen¶

Rufe im Browser die folgende Adresse auf:

http://<server-ip>:3456/api/v1/info

Ersetze <server-ip> wieder durch die Server-IP. Erscheint eine JSON-Antwort mit Versions- und Funktionsangaben, sind Oberfläche und API erreichbar.

7. Datenbank und Anhänge sichern¶

Erstelle zuerst im Arbeitsordner einen logischen PostgreSQL-Export. Der Befehl läuft im Datenbankcontainer und schreibt die Ausgabe auf den Host:

cd /opt/vikunja
docker compose exec -T db pg_dump -U vikunja vikunja > "backup/vikunja-$(date +%F).sql"

Packe Datenbankexport, Anhänge, Compose-Datei und Geheimnisse in ein Archiv:

sudo tar -czf "$HOME/vikunja-backup-$(date +%F).tar.gz" compose.yaml .env files backup

Gelöschte Projekte sind endgültig weg

Vikunja besitzt für gelöschte Projekte keinen Papierkorb. Kopiere das Archiv regelmäßig auf ein zweites Speichermedium und teste die Wiederherstellung.

Für einen sicheren Rückweg stoppst du den Stack, benennst /opt/vikunja um und richtest eine leere Installation mit derselben Konfiguration ein. Kopiere files zurück und spiele den SQL-Export nur in eine leere Datenbank ein:

cat <vikunja-backup.sql> | docker compose exec -T db psql -U vikunja vikunja

Ersetze <vikunja-backup.sql> durch den vollständigen Pfad zum entpackten SQL-Export. Überschreibe keine produktive Datenbank ohne zusätzliche Sicherung.

8. Vikunja aktualisieren¶

Erstelle zuerst eine Sicherung. Lade danach im Arbeitsordner die aktuellen Images:

cd /opt/vikunja
docker compose pull

Erstelle die Container neu; die Daten in db und files bleiben erhalten:

docker compose up -d

Prüfe anschließend Status und Protokoll:

docker compose ps
docker compose logs --tail=100 vikunja

9. Typische Fehler beheben¶

Bei unauthorized während der Registrierung kontrollierst du die öffentliche URL:

docker compose config | grep VIKUNJA_SERVICE_PUBLICURL

Sie muss einschließlich Port und abschließendem Schrägstrich zur Browseradresse passen. Scheitert ein Anhang mit permission denied, korrigiere den Besitz:

sudo chown -R 1000:1000 /opt/vikunja/files
docker compose restart vikunja

Ist die Datenbank noch nicht bereit, warte kurz und prüfe beide Protokolle:

docker compose logs --tail=100 db vikunja

Bei address already in use ist Port 3456 belegt. Ändere sowohl die linke Portnummer im Port-Mapping als auch den Port in VIKUNJA_SERVICE_PUBLICURL auf denselben freien Wert.

10. Quellen und Video¶

Fertig¶

Vikunja läuft jetzt mit PostgreSQL und speichert Anhänge dauerhaft unter /opt/vikunja/files. Öffne deine Testaufgabe, hänge eine kleine Datei an und starte die Container neu. Sind Aufgabe und Anhang danach noch vorhanden, funktioniert die Grundinstallation.