Vikunja verwaltet Aufgaben und Projekte auf Ihrem Synology NAS. Liste, Kanban, Gantt und Kalender bieten verschiedene Ansichten auf denselben Bestand. Teamfreigaben, CalDAV und eine REST-API ergänzen die Weboberfläche. Für Zeiterfassung und umfassende Ressourcenplanung bietet OpenProject auf dem Synology NAS mehr Funktionen.

Voraussetzungen

Synology NAS mit x86_64-Prozessor (z. B. DS923+, DS723+, DS1522+, DS1821+) und DSM 7.2 oder neuer
Container Manager aus dem Synology Package Center installiert
Mindestens 512 MB freier RAM (empfohlen: 1 GB für Vikunja + PostgreSQL zusammen)
Mindestens 2 GB freier Speicherplatz auf /volume1
Eigene Domain oder Synology QuickConnect/DDNS mit aktivem HTTPS-Zertifikat (Let's Encrypt über DSM)
SSH-Zugriff auf das NAS für die Berechtigungsschritte (Anleitung: SSH auf dem Synology NAS aktivieren und verbinden)
Internet-Zugang für den Docker-Image-Pull

Hardware für diese Anleitung

Enthält Werbelinks

Synology mit Container Manager	Container laufen nur auf Modellen mit Container Manager, vor allem der Plus-Serie. Vor dem Kauf die Kompatibilitätsliste von Synology prüfen. Bei uns läuft eine DS920+.	Synology bei Amazon (Werbelink)
NAS-Festplatten	Für den Dauerbetrieb Platten mit CMR-Technik wählen, für RAID 1 zwei gleich große.	NAS-Platten bei Amazon (Werbelink)
RAM-Erweiterung	Mehrere Container gleichzeitig brauchen Speicher. Viele Plus-Modelle lassen sich aufrüsten, das passende Modul steht im Datenblatt.	Bei Amazon ansehen (Werbelink)

Vorhandene Hardware reicht oft. Die Liste zeigt, worauf es bei einem Neukauf ankommt. * Werbelink

Schritt 1: Verzeichnisse anlegen und Berechtigungen setzen

Öffnen Sie die File Station in DSM und legen Sie folgende Ordnerstruktur unter /volume1/docker/ an (Grundlagen dazu: Docker-Ordner und Berechtigungen auf dem Synology NAS):

/volume1/docker/vikunja/
├── data/      ← Dateianhänge, Projektbilder, Uploads
└── db/        ← PostgreSQL-Datenbankdaten

Das data-Verzeichnis muss dem internen Container-Benutzer mit UID 1000 gehören, damit Vikunja Dateien schreiben kann. Verbinden Sie sich per SSH mit dem NAS und führen Sie aus:

sudo chown -R 1000:1000 /volume1/docker/vikunja/data

PostgreSQL setzt die Rechte des Datenverzeichnisses beim Start selbst.

Verifizieren: Prüfen Sie die Berechtigungen:

ls -la /volume1/docker/vikunja/

Vor dem Containerstart:

drwxr-xr-x  2 1000 1000  data
drwxr-xr-x  2 root root  db

Schritt 2: JWT-Secret generieren

Vikunja signiert alle Benutzer-Sessions mit einem geheimen Schlüssel (VIKUNJA_SERVICE_SECRET). Ist dieser Wert nicht fest gesetzt, generiert der Container bei jedem Neustart einen neuen Zufallswert, alle eingeloggten Benutzer werden sofort ausgeloggt. Erzeugen Sie deshalb jetzt ein sicheres Secret über SSH auf dem NAS:

openssl rand -hex 32

Kopieren Sie den 64-Zeichen-Wert für die compose.yaml.

Wichtig: Der früher verwendete Variablenname VIKUNJA_SERVICE_JWTSECRET ist offiziell deprecated. Verwenden Sie ausschließlich VIKUNJA_SERVICE_SECRET, sonst kann es in neueren Versionen zu Problemen bei der Token-Validierung kommen.

Verifizieren: Die Ausgabe von openssl rand -hex 32 muss exakt 64 Zeichen lang sein. Prüfen Sie das mit:

openssl rand -hex 32 | wc -c

Erwartetes Ergebnis: 65 (64 Zeichen + Zeilenumbruch).

Schritt 3: compose.yaml erstellen

Legen Sie im Verzeichnis /volume1/docker/vikunja/ eine Datei namens compose.yaml an. Ersetzen Sie die Platzhalter durch Ihre tatsächlichen Werte:

Parameter	Wert (Beispiel)	Hinweis
Image	`vikunja/vikunja:2.7.0`	Stabile Version Oktober 2026; gepinnter Tag für Produktion
Port	`3456:3456`	HTTP; wird per Reverse Proxy zu HTTPS
Datenbank	`postgres:18`	Empfohlen für Mehrbenutzerbetrieb
data-Volume	`/volume1/docker/vikunja/data:/app/vikunja/files`	Anhänge und Uploads; UID 1000 erforderlich
db-Volume	`/volume1/docker/vikunja/db:/var/lib/postgresql`	Datenbankdaten

services:
  vikunja:
    image: vikunja/vikunja:2.7.0
    container_name: vikunja
    environment:
      VIKUNJA_SERVICE_PUBLICURL: "https://vikunja.meinedomain.synology.me"
      VIKUNJA_SERVICE_SECRET: "HIER_DEN_GENERIERTEN_64-ZEICHEN-STRING_EINTRAGEN"
      VIKUNJA_SERVICE_TIMEZONE: "Europe/Berlin"
      VIKUNJA_SERVICE_ENABLEREGISTRATION: "true"
      VIKUNJA_SERVICE_ENABLECALDAV: "true"
      VIKUNJA_DATABASE_TYPE: postgres
      VIKUNJA_DATABASE_HOST: db
      VIKUNJA_DATABASE_USER: vikunja
      VIKUNJA_DATABASE_PASSWORD: "sicheresDbPasswort"
      VIKUNJA_DATABASE_DATABASE: vikunja
    ports:
      - "3456:3456"
    volumes:
      - /volume1/docker/vikunja/data:/app/vikunja/files
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

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

VIKUNJA_SERVICE_PUBLICURL: Tragen Sie die tatsächliche HTTPS-Adresse ein. Die Oberfläche nutzt sie für API-Anfragen. Eine falsche Domain führt zu „Failed to fetch“.
VIKUNJA_SERVICE_TIMEZONE: Nur tz-Datenbank-Namen wie Europe/Berlin oder Europe/Vienna sind gültig. Werte wie UTC+2 oder GMT+2 funktionieren nicht und führen zu falschen Zeitstempeln.
depends_on mit healthcheck: Stellt sicher, dass Vikunja erst startet, wenn PostgreSQL bereit ist. Nie weglassen.
POSTGRES_PASSWORD und VIKUNJA_DATABASE_PASSWORD müssen identisch sein.

Verifizieren: Prüfen Sie die gespeicherte Datei auf verbliebene Platzhalter und passende Einrückung. Die beiden Datenbankpasswörter müssen übereinstimmen.

Schritt 4: Container-Projekt im Container Manager starten

Öffnen Sie den Container Manager in DSM und legen Sie ein neues Compose-Projekt an (Schritt für Schritt: Container Manager: Docker-Compose-Projekt anlegen, starten und aktualisieren). Wichtig: Wählen Sie „Projekt“ und nicht „Container“, nur als Projekt werden beide Services im selben Docker-Netzwerk gestartet, damit der vikunja-Container den db-Service per Hostname erreichen kann.

Geben Sie als Projektpfad /volume1/docker/vikunja an und importieren Sie die compose.yaml. Container Manager lädt dann automatisch die Images vikunja/vikunja:2.7.0 und postgres:18 aus dem Docker Hub und startet beide Container.

Verifizieren: Im Container Manager sollten nach wenigen Minuten beide Container den Status „Wird ausgeführt“ zeigen. Prüfen Sie die Logs des vikunja-Containers auf:

Ran all migrations successfully.
HTTP server listening on :3456

Die Warnung No license key configured. Pro features have been disabled. ist normal: Seit Version 2.4 kennt Vikunja optionale Pro-Funktionen mit Lizenzschlüssel, alle in dieser Anleitung genutzten Funktionen laufen ohne.

Erscheinen Fehler wie dial tcp: connection refused, hat PostgreSQL noch nicht geantwortet, warten Sie 30 Sekunden und sehen Sie erneut nach. Der Healthcheck-Mechanismus fängt das in aller Regel automatisch ab.

Schritt 5: Reverse Proxy und HTTPS einrichten

Damit Sie Vikunja über Ihre Domain per HTTPS erreichen, richten Sie in DSM einen Reverse Proxy ein. Gehen Sie zu Systemsteuerung → Anmeldeportal → Erweitert → Reverse Proxy und legen Sie eine neue Regel an:

Quelle: HTTPS, Ihre Domain (z. B. vikunja.meinedomain.synology.me), Port 443
Ziel: HTTP, localhost, Port 3456

Aktivieren Sie unter „Benutzerdefinierter Header“ die WebSocket-Unterstützung oder tragen Sie folgende Header manuell ein, damit Vikunjas Echtzeit-Updates funktionieren:

Upgrade: $http_upgrade
Connection: upgrade

Für die DSM-Firewall müssen Sie Port 3456 nur dann öffnen, wenn Sie direkt (ohne Reverse Proxy) auf Vikunja zugreifen wollen. Bei Nutzung des Reverse Proxys reicht Port 443. Details: DSM-Firewall auf dem Synology NAS: Ports für Docker-Container freigeben.

Verifizieren: Rufen Sie https://vikunja.meinedomain.synology.me im Browser auf. Sie sollten die Vikunja-Anmeldeseite sehen. Ein gültiges HTTPS-Zertifikat ohne Browser-Warndialog bestätigt, dass der Reverse Proxy korrekt konfiguriert ist.

Schritt 6: Ersten Benutzer registrieren und Registrierung sperren

Bei Vikunja gibt es keinen vordefinierten Admin-Account: Der erste registrierte Benutzer wird automatisch Administrator. Klicken Sie auf der Anmeldeseite auf „Registrieren“ und legen Sie Ihren Admin-Account an. Danach können sich bei Bedarf alle Teammitglieder selbst registrieren, lassen Sie dafür VIKUNJA_SERVICE_ENABLEREGISTRATION: "true" temporär aktiv.

Sobald alle gewünschten Benutzer angelegt sind, setzen Sie in der compose.yaml die Variable auf "false" und starten Sie den Container im Container Manager neu (Projekt → Stoppen → Starten). Das verhindert, dass sich unbekannte Personen selbst einen Account erstellen.

Für Team-Einladungen ohne offene Registrierung können Sie alternativ den SMTP-Mailer konfigurieren: Tragen Sie dazu VIKUNJA_MAILER_ENABLED: "true" und die passenden VIKUNJA_MAILER_*-Variablen (Host, Port, Absender) in die compose.yaml ein.

Verifizieren: Melden Sie sich mit dem gerade angelegten Account an. Unter Einstellungen → Allgemein sehen Sie die Versionsnummer (sollte 2.7.0 lauten) und können bestätigen, dass der Login funktioniert.

Schritt 7: Erstes Projekt und Kanban-Board einrichten

Nach dem Login landen Sie auf der Übersicht. Legen Sie über das „+“-Symbol ein neues Projekt an. In der Projektansicht können Sie oben rechts zwischen den vier Ansichtsmodi wechseln:

Liste: klassische Aufgabenliste mit Fälligkeitsdaten und Prioritäten
Kanban: Spalten nach Status (z. B. „Offen“, „In Arbeit“, „Erledigt“)
Gantt: Zeitplan-Ansicht für Projekte mit Abhängigkeiten
Kalender: Aufgaben als Kalendereinträge nach Fälligkeitsdatum

Über „Teilen“ vergeben Sie projektbezogene Rechte zum Lesen, Schreiben oder Verwalten. Für Ressourcenplanung und Zeiterfassung eignet sich OpenProject auf dem Synology NAS.

Vikunja mit Kanban-Ansicht und der Aufgabe Sicherung prüfen — Kanban-Ansicht des Projekts mit einer angelegten Aufgabe.

Verifizieren: Erstellen Sie im Kanban-Board eine Testaufgabe, verschieben Sie sie von „Offen“ in „In Arbeit“ und prüfen Sie, ob die Änderung nach einem Browser-Reload erhalten bleibt. Das bestätigt, dass die Datenbankverbindung zu PostgreSQL stabil funktioniert.

Schritt 8: CalDAV-Abonnement im Kalender einrichten

Vikunja ist standardmäßig als CalDAV-Server aktiv. Aufgaben mit Fälligkeitsdaten können so in Apple Kalender, Thunderbird oder iOS/Android-Kalender-Apps als Einträge angezeigt werden, ohne zusätzliche Konfiguration am Server.

https://vikunja.meinedomain.synology.me/dav/

Apple Kalender (macOS): Kalender → Einstellungen → Accounts → Account hinzufügen → Anderen CalDAV-Account hinzufügen. Server-URL, Vikunja-Benutzername und Passwort eingeben.
iOS: Einstellungen → Kalender → Accounts → Account hinzufügen → Sonstige → CalDAV-Account hinzufügen.
Thunderbird: Im Kalender „Neuer Kalender“ → „Im Netzwerk“ → CalDAV, dann die obige URL eingeben.

Möchten Sie CalDAV deaktivieren, setzen Sie VIKUNJA_SERVICE_ENABLECALDAV: "false" in der compose.yaml und starten Sie den Container neu. Wer Vikunja mit einem Terminbuchungs-Tool kombinieren möchte, findet mit Cal.com auf dem Synology NAS eine selbst gehostete Calendly-Alternative, die CalDAV-fähig ist.

Verifizieren: Fügen Sie den CalDAV-Account im Kalender-Client hinzu. Erstellen Sie in Vikunja eine Aufgabe mit Fälligkeitsdatum und warten Sie 1 bis 2 Minuten. Der Eintrag sollte im Kalender-Client erscheinen. Fehlt er, prüfen Sie, ob VIKUNJA_SERVICE_ENABLECALDAV: "true" gesetzt ist und der Reverse Proxy CalDAV-Requests korrekt weiterleitet.

Troubleshooting / Typische Fehler

„Session nach Neustart ungültig“ / alle Benutzer ausgeloggt: VIKUNJA_SERVICE_SECRET ist nicht gesetzt oder leer. Lösung: In der compose.yaml einen festen 64-Zeichen-Zufallsstring eintragen (openssl rand -hex 32) und den Container neu erstellen.
Zeitstempel um Stunden verschoben: Ursache ist ein UTC/GMT-Offset-Format wie UTC+2. Korrekt ist ein tz-Datenbank-Name wie Europe/Berlin. Compose-Datei anpassen, Container neu starten.
„Failed to fetch“ im Browser: Prüfen Sie VIKUNJA_SERVICE_PUBLICURL. Im Test verhinderte die unveränderte Beispieldomain den Zugriff. Nach Eintragen der tatsächlichen Adresse und Neuerstellen des Containers funktionierte die Oberfläche.
„Permission denied“ beim Hochladen von Anhängen: Das data-Verzeichnis gehört nicht UID 1000. Lösung: sudo chown -R 1000:1000 /volume1/docker/vikunja/data.
„connection refused“ beim Vikunja-Start: PostgreSQL war noch nicht bereit. Der depends_on-Block mit condition: service_healthy und dem pg_isready-Healthcheck löst das in aller Regel automatisch. Prüfen Sie, ob Sie diesen Block entfernt haben.
Login schlägt fehl / Token-Fehler: Alter Variablenname VIKUNJA_SERVICE_JWTSECRET statt VIKUNJA_SERVICE_SECRET verwendet. Variable umbenennen, Container neu erstellen.
Vikunja-Container kann „db“ nicht erreichen: Das Compose-Projekt wurde als Einzelcontainer statt als „Projekt“ angelegt. Im Container Manager als neues Projekt neu importieren.
Echtzeit-Updates funktionieren nicht: WebSocket-Header fehlen im Reverse Proxy. Upgrade: $http_upgrade und Connection: upgrade unter „Benutzerdefinierter Header“ ergänzen.
PostgreSQL startet nicht / „data directory has wrong ownership“: Lösung: sudo chown -R 999:999 /volume1/docker/vikunja/db (UID 999 ist der postgres-User im offiziellen Image).

Häufige Fragen

Wie generiere ich ein sicheres VIKUNJA_SERVICE_SECRET?

Per SSH auf dem Synology NAS: openssl rand -hex 32 erzeugt einen 64 Zeichen langen Hex-String. Den Wert tragen Sie in der compose.yaml bei VIKUNJA_SERVICE_SECRET ein und starten den Container danach neu. Alternativ können Sie in einem Passwort-Manager einen langen Zufallsstring generieren.

Wie abonniere ich Vikunja-Aufgaben per CalDAV im Kalender?

CalDAV ist standardmäßig aktiv. Die Server-Adresse lautet https://ihre-vikunja-domain.tld/dav/. In Apple Kalender, iOS, Thunderbird oder Android-Kalender-Apps fügen Sie einen neuen CalDAV-Account mit dieser URL sowie Ihrem Vikunja-Benutzernamen und Passwort hinzu. Aufgaben mit Fälligkeitsdatum erscheinen dann automatisch als Kalendereinträge.

Was ist der Unterschied zwischen Vikunja und OpenProject?

Vikunja konzentriert sich auf Aufgaben, vier Ansichtsmodi und CalDAV. OpenProject bietet zusätzlich Zeiterfassung, Ressourcenplanung und Budgetverwaltung, benötigt aber mehr Ressourcen.

Wie lade ich Teammitglieder ein?

Ohne konfigurierten Mailer gibt es keine E-Mail-Einladung. Der einfachste Weg: Lassen Sie VIKUNJA_SERVICE_ENABLEREGISTRATION: "true" solange aktiv, bis sich alle Teammitglieder selbst registriert haben. Danach auf "false" setzen und den Container neu starten. Alternativ können Sie über die VIKUNJA_MAILER_*-Variablen (z. B. Gmail-SMTP-Relay) E-Mail-Einladungen aktivieren.

Wie aktualisiere ich Vikunja auf eine neue Version?

Sichern Sie vor Updates data und die gestoppte PostgreSQL-Datenbank. Ändern Sie den Image-Tag und wählen Sie im Container Manager „Projekt aktualisieren“. Im früheren Test von 2.3.0 auf 2.7.0 mit PostgreSQL 18 blieben Benutzer, Projekte und CalDAV erhalten. Seit 2.5 übernimmt Vikunja VIKUNJA_SERVICE_JWTSECRET als VIKUNJA_SERVICE_SECRET; benennen Sie die Variable um. Prüfen Sie bei eigenen API-Skripten die in 2.7 geänderten Fehlercodes.

Kann ich von SQLite auf PostgreSQL migrieren?

Ja, Vikunja bietet einen eingebauten Migrations-Befehl. Details dazu finden Sie in der offiziellen Dokumentation unter „Migrating to a new database backend“. Für Neuinstallationen empfiehlt es sich, direkt mit PostgreSQL zu starten, da SQLite für den Mehrbenutzerbetrieb nicht geeignet ist.

Fazit

Vikunja verbindet Aufgabenverwaltung, Teamfreigaben und CalDAV auf dem eigenen NAS. PostgreSQL und ein dauerhaft gespeicherter Sitzungsschlüssel bilden die technische Grundlage. Schließen Sie nach der Kontoanlage die Registrierung und prüfen Sie Sicherungen vor Updates.

Weiterführende Anleitungen und Quellen

OpenProject auf dem Synology NAS installieren: Projektmanagement mit Gantt und Tickets, die vollwertige PM-Suite für Teams mit komplexen Anforderungen
Cal.com auf dem Synology NAS installieren: Terminbuchung als Calendly-Alternative, ergänzendes Terminbuchungs-Tool mit CalDAV-Integration
Container Manager: Docker-Compose-Projekt anlegen, starten und aktualisieren
SSH auf dem Synology NAS aktivieren und verbinden

Offizielle Quellen: Vikunja Dokumentation, Full Docker Example | Vikunja Konfigurationsoptionen (Umgebungsvariablen) | Vikunja auf GitHub