Docker-Ordner und Berechtigungen auf dem Synology NAS: File Station, PUID und PGID

Wer seinen ersten Docker-Container auf dem Synology NAS zum Laufen bringen will, stolpert früh über eine Frage, die in keiner App-Anleitung ausführlich erklärt wird: Warum erscheint im Log „Permission denied“, obwohl der Ordner doch existiert? Die Antwort liegt in der Kombination aus falsch gesetzten Eigentümern und falsch konfigurierten Umgebungsvariablen PUID und PGID. Diese Grund-Anleitung legt das Fundament, das jede weitere App-Anleitung voraussetzt, von Sonarr über Nextcloud bis Vaultwarden.

Voraussetzungen

• Synology NAS mit DSM 7.2 oder höher und Container Manager (x86 oder ARM64; Modellliste im Paketzentrum), mindestens 2 GB RAM
• Container Manager Paket (im Paketzentrum installieren)
• Admin-Zugang zur DSM-Weboberfläche
• SSH-Zugang (temporär aktiviert – Details in der Grund-Anleitung SSH auf dem Synology NAS aktivieren)
• Optional: Snapshot Replication Paket für Snapshot-Unterstützung

Hintergrund: Warum brauchen linuxserver.io-Images PUID und PGID?

Docker-Container laufen standardmäßig als root. Jede Datei, die ein Container anlegt, gehört dann root und nicht Ihrem NAS-Benutzer. Als normaler Benutzer haben Sie darauf keinen Schreibzugriff, und ein kompromittierter Container richtet mehr Schaden an als nötig.

Die linuxserver.io-Images lösen das so: Sie lesen beim Start die Umgebungsvariablen PUID (Process User ID) und PGID (Process Group ID) aus und starten die Anwendung danach unter genau dieser Benutzer-ID. Alle erzeugten Dateien gehören damit Ihrem NAS-Benutzer.

Was passiert bei falschen Werten? Der Container startet oft trotzdem, arbeitet aber nicht korrekt. Im Log erscheinen Fehler wie Permission denied oder Unable to read/write to folder. Die App bleibt stumm oder zeigt eine leere Oberfläche, weil sie ihre Konfiguration nicht schreiben kann.

Wichtig für Synology: Viele Anleitungen empfehlen pauschal PUID=1000 – das ist der typische Wert auf Ubuntu- oder Debian-Systemen. Auf Synology beginnen Benutzer-UIDs jedoch meist bei 1026. Mit PUID=1000 verweisen Sie in der Regel auf keinen existierenden Benutzer. Ermitteln Sie die Werte daher immer per id-Befehl.

Schritt 1: Freigegebenen Ordner „docker“ anlegen

Öffnen Sie in DSM Systemsteuerung › Freigegebene Ordner › Erstellen. Vergeben Sie den Namen docker (Kleinschreibung) und wählen Sie das Volume, typischerweise Volume 1.

Empfohlene Einstellungen beim Anlegen:

• Papierkorb aktivieren: Ja, schützt vor versehentlichem Löschen von Konfigurationsdateien. Leeren Sie ihn regelmäßig, da Docker viele kleine Dateien erzeugt.
• Data Checksum: Deaktiviert lassen. Die Option kostet Schreibleistung und lässt sich nachträglich nur durch Neuanlage des Ordners ändern.
• Snapshots (optional): Wenn das Snapshot Replication Paket installiert ist, aktivieren Sie Snapshots für den docker-Ordner. Das ermöglicht eine schnelle Wiederherstellung nach fehlgeschlagenen Container-Updates.

Verifizieren: In der File Station erscheint links der Ordner docker. Er ist leer.

Schritt 2: Unterordner je App in der File Station anlegen

Öffnen Sie in der File Station den Ordner docker. Legen Sie für jede App einen eigenen Unterordner an: Rechtsklick im rechten Bereich › Ordner erstellen.

Konvention: Immer Kleinschreibung. Linux unterscheidet Groß- und Kleinschreibung: Sonarr ist nicht sonarr. Passt die Schreibweise nicht, legt Docker einen neuen, root-eigenen Ordner an.

Die empfohlene Struktur sieht so aus:

/volume1/docker/
├── sonarr/
│   └── config/
├── radarr/
│   └── config/
└── nextcloud/
    ├── config/
    └── data/

Legen Sie zuerst den App-Ordner an (z. B. sonarr), darin den Unterordner config. Manche Apps benötigen zusätzlich data, das steht in der jeweiligen App-Anleitung. Faustregel: Der Pfad im volumes-Abschnitt der Compose-Datei für :/config lautet immer /volume1/docker/<app>/config.

Verifizieren: In der File Station existiert docker/sonarr/config und ist leer, bevor der Container zum ersten Mal startet.

Schritt 3: PUID und PGID per SSH ermitteln

Aktivieren Sie SSH vorübergehend und verbinden Sie sich mit dem NAS, Details in der Grund-Anleitung SSH auf dem Synology NAS aktivieren. Führen Sie dann diesen Befehl aus:

id <benutzername>

Ersetzen Sie <benutzername> durch Ihren NAS-Benutzer, z. B. admin oder einen dedizierten Docker-Benutzer. Typische Ausgabe:

uid=1026(admin) gid=100(users) groups=100(users),101(administrators)

Daraus lesen Sie ab:

Variable	Wert (Beispiel)	Bedeutung
PUID	1026	uid= aus der id-Ausgabe
PGID	100	gid= aus der id-Ausgabe
TZ	Europe/Berlin	Zeitzone im Container

Die PGID 100 ist auf Synology die Standard-GID der Gruppe users – fast alle NAS-Benutzer sind Mitglied. Eine eigene Gruppe (z. B. dockergroup) hat eine andere GID, lesen Sie sie aus der id-Ausgabe ab.

Verifizieren: Die Ausgabe von id <benutzername> zeigt numerische uid- und gid-Werte. Notieren Sie sie für die Compose-Datei. Deaktivieren Sie SSH nach Schritt 4 wieder unter Systemsteuerung › Terminal & SNMP › Terminal.

Schritt 4: Eigentümer korrekt setzen (chown)

Damit der Container unter Ihrem Benutzer schreiben kann, muss /volume1/docker samt Inhalt diesem Benutzer gehören. Führen Sie per SSH aus:

sudo chown -R <benutzername>:users /volume1/docker

-R (rekursiv) setzt den Eigentümer auch für alle Unterordner und Dateien.

Nach größeren Kopieraktionen per SMB oder SFTP führen Sie den Befehl erneut aus, da kopierte Dateien dem kopierenden Benutzer gehören.

Alternativ setzen Sie den Eigentümer in der File Station: Rechtsklick auf docker › Eigenschaften › Berechtigungen, mit Haken bei „Auf alle Unterordner und Dateien anwenden“.

Verifizieren: Prüfen Sie den Eigentümer per SSH:

ls -la /volume1/docker/

Beispiel für eine korrekte Ausgabe:

drwxr-xr-x  3 admin  users  4096 Jun 10 10:00 sonarr

Der dritte Eintrag (hier admin) ist der Eigentümer – er muss Ihr NAS-Benutzer sein.

Schritt 5: PUID und PGID in die Compose-Datei eintragen

Tragen Sie die ermittelten Werte als Umgebungsvariablen in die Compose-Datei ein. Beispiel mit Sonarr:

services:
  sonarr:
    image: lscr.io/linuxserver/sonarr:4.0.20
    container_name: sonarr
    environment:
      - PUID=1026
      - PGID=100
      - TZ=Europe/Berlin
    volumes:
      - /volume1/docker/sonarr/config:/config
      - /volume1/data/media/tv:/tv
    ports:
      - "8989:8989"
    restart: unless-stopped

Ersetzen Sie 1026 und 100 durch Ihre Werte aus Schritt 3. Das Prinzip gilt für alle linuxserver.io-Images wie Radarr, Jellyfin oder Nextcloud.

Hinweis zum Image-Tag: Ein festes Tag (hier 4.0.20, Stand September 2026) verhindert unkontrollierte Updates. :latest zieht bei jedem Update die neueste Version.

Hinweis zum --user-Flag: linuxserver.io empfiehlt weiterhin PUID und PGID. Der Betrieb mit --user ist laut Doku ein Thema für Fortgeschrittene mit Einschränkungen und für diese Anleitung nicht nötig.

Wie Sie das Compose-Projekt im Container Manager anlegen und starten, erklärt die Grund-Anleitung Container Manager: Docker-Compose-Projekt anlegen.

Verifizieren: Starten Sie den Container und prüfen Sie die ersten Log-Zeilen im Container Manager. Ein linuxserver.io-Image gibt beim Start aus, unter welcher UID es läuft:

-------------------------------------
          _         ()
         | |  ___   _    __
         | | / __| | |  /  \
         | | \__ \ | | | () |
         |_| |___/ |_|  \__/

Brought to you by linuxserver.io
-------------------------------------

User uid:    1026
User gid:    100

Stimmen die Werte mit Ihrer Eingabe überein, ist alles korrekt konfiguriert.

Best Practice: Dedizierter Docker-Benutzer (optional)

Anstatt den admin-Account für PUID/PGID zu verwenden, empfiehlt sich ein dedizierter Benutzer ohne Adminrechte – z. B. dockerlimited. Legen Sie ihn unter Systemsteuerung › Benutzer & Gruppe an. Er erhält nur Lese- und Schreibzugriff auf den Ordner docker (und ggf. data), aber keine Adminrechte.

Für den Einstieg funktioniert auch der admin-Account. Mit dessen Rechten hat ein kompromittierter Container aber potenziell Zugriff auf alle Freigaben, ein dedizierter Benutzer begrenzt den Schaden.

Seine UID ermitteln Sie wie in Schritt 3 mit id dockerlimited und tragen sie als PUID ein.

Troubleshooting / Typische Fehler

• „Permission denied“ im Container-Log: PUID oder PGID stimmen nicht mit dem Eigentümer der Ordner überein. Prüfen Sie mit ls -la /volume1/docker/<app> per SSH, wem der Ordner gehört, und korrigieren Sie mit sudo chown -R <benutzer>:users /volume1/docker oder passen Sie PUID/PGID an.
• PUID=1000 führt zu leerem Container: Auf Synology gibt es keinen Benutzer mit UID 1000. Der Container startet, kann aber nichts schreiben. Immer erst id <benutzername> ausführen und den tatsächlichen Wert verwenden.
• Ordner mit Großbuchstaben angelegt (z. B. „Sonarr“): Docker erstellt dann einen neuen, root-eigenen Ordner mit der Schreibweise aus der Compose-Datei. Lösung: Ordner in der File Station umbenennen und Compose-Datei anpassen.
• Ordner nicht vor Container-Start angelegt: Docker erstellt fehlende Host-Verzeichnisse automatisch – aber mit root als Eigentümer. Immer zuerst die Ordner in der File Station anlegen und dann chown setzen, bevor der Container startet.
• chown ohne -R ausgeführt: Nur der Hauptordner hat den richtigen Eigentümer, Unterordner und Dateien gehören weiterhin root. Befehl mit -R wiederholen.
• Papierkorb aktiviert, aber nie geleert: Er füllt sich mit vielen kleinen Dateien. Regelmäßig leeren oder deaktivieren und stattdessen Snapshots nutzen.
• PGID einer eigenen Gruppe falsch eingetragen: Wer eine eigene Gruppe (z. B. dockergroup) anlegt, muss deren GID aus der id-Ausgabe ablesen – sie ist nicht 100. Die falsche PGID führt zu Permission-Fehlern, auch wenn PUID korrekt ist.
• SSH nicht wieder deaktiviert: Ein dauerhaft offener SSH-Dienst ist unnötige Angriffsfläche. Deaktivieren Sie ihn unter Systemsteuerung › Terminal & SNMP.

Häufige Fragen

Woher weiß ich, welche PUID und PGID ich nehmen soll?

Per SSH mit dem Befehl id <benutzername> – z. B. id admin. Die Ausgabe zeigt uid=XXXX und gid=XXXX. Diese Zahlen sind PUID und PGID. Den SSH-Zugang richten Sie wie in der Grund-Anleitung SSH auf dem Synology NAS aktivieren beschrieben ein.

Muss ich einen eigenen Docker-Benutzer anlegen oder reicht der admin-Account?

Für den Einstieg reicht der admin-Account. Für den produktiven Betrieb empfiehlt sich ein Benutzer ohne Adminrechte, siehe Abschnitt „Best Practice“.

Kann ich PUID und PGID auch im Container Manager ohne compose.yaml eintragen?

Ja. Beim Erstellen oder Bearbeiten eines Containers unter Umgebung tragen Sie Umgebungsvariablen als Schlüssel-Wert-Paare ein: PUID = 1026, PGID = 100. Für die meisten Zwecke ist eine Compose-Datei aber übersichtlicher und einfacher zu versionieren.

Was ist der Unterschied zwischen /volume1/docker und /config im Container?

/volume1/docker/sonarr/config ist der Host-Pfad auf dem NAS, er steht links vom Doppelpunkt in volumes:. /config ist der Container-Pfad, unter dem das Image seine Konfiguration erwartet – den gibt der Image-Hersteller vor. Diese beiden Pfade haben nichts miteinander zu tun; Docker verknüpft sie nur beim Start.

Muss ich den Papierkorb für den docker-Ordner aktivieren?

Empfohlen als Sicherheitsnetz, aber regelmäßig leeren. Alternative: Papierkorb aus, dafür Snapshots (Snapshot Replication).

Was passiert, wenn ich PUID und PGID nicht angebe?

linuxserver.io-Images verwenden dann Standardwerte (meist UID 911). Die Prozesse laufen dann als interner Benutzer, der auf dem NAS nicht existiert. Dateien in gemounteten Ordnern gehören einer unbekannten UID und lassen sich in der File Station nicht bearbeiten. Geben Sie PUID und PGID immer explizit an.

Fazit

Die Ordnerstruktur und die korrekte Berechtigungskonfiguration sind das unsichtbare Fundament jedes Docker-Stacks auf dem Synology NAS. Wer PUID/PGID falsch setzt, sucht später lange nach Fehlern. Der Aufwand ist überschaubar: Freigegebenen Ordner anlegen, Unterordner in der File Station erstellen, einmal id <benutzername> per SSH ausführen, chown setzen – fertig. Jede App-Anleitung auf dieser Website baut auf genau diesen Schritten auf und setzt sie als erledigt voraus.

Weiterführende Anleitungen und Quellen

• SSH auf dem Synology NAS aktivieren und verbinden: PuTTY und Terminal – SSH-Zugang für Schritt 3
• Container Manager auf dem Synology NAS: Docker-Compose-Projekt anlegen, starten und aktualisieren – der nächste logische Schritt nach dieser Grund-Anleitung
• DSM-Firewall auf dem Synology NAS: Ports für Docker-Container freigeben – Firewall-Regeln für Container-Dienste
• Docker Compose: Multi-Container-Stacks aufbauen – Grundlagen für komplexere Compose-Setups

Quellen: linuxserver.io – Understanding PUID and PGID | TRaSH Guides – Synology Folder Structure | Marius Hosting – Synology: How to Find UID and GID | Synology Knowledge Center – Freigegebenen Ordner erstellen