code-server auf dem Synology NAS installieren: VS Code im Browser

Wer Compose-Dateien, Shell-Skripte oder Konfigurationen direkt auf dem Synology NAS bearbeiten will, greift meist zu SSH und einem Kommandozeilen-Editor. Mit code-server geht das komfortabler: Das Projekt coder/code-server verpackt VS Code als Webserver, der vollständig im Browser läuft – mit echtem Terminal, Extension-Marketplace, IntelliSense und integrierter Git-Unterstützung. Das linuxserver.io-Image bringt PUID/PGID-Support mit, sodass der Container auf dem NAS mit den richtigen Dateiberechtigungen arbeitet. Das Ergebnis ist eine vollwertige Entwicklungsumgebung im Browser, ohne lokale IDE und ohne SSH-Konfiguration an jedem Arbeitsplatz.

Voraussetzungen

• Synology NAS mit DSM 7.2 und Container Manager (x86-64 oder ARM64)
• Container Manager aus dem Package Center installiert
• Mindestens 1 GB freier RAM für den code-server-Container
• SSH-Zugang zum NAS (einmalig zum Ermitteln von PUID und PGID) – Schritt-für-Schritt: SSH auf dem Synology NAS aktivieren und verbinden
• Ordner /volume1/docker/code-server/config bereits angelegt (File Station oder SSH) – Hintergründe zu Ordnern und Berechtigungen: Docker-Ordner und Berechtigungen auf dem Synology NAS
• Optional: synology.me-DDNS oder eigene Domain für HTTPS-Zugriff von außen

Eckdaten auf einen Blick

Eigenschaft	Wert
Image	lscr.io/linuxserver/code-server:latest
Aktueller Build	4.143.1-ls373 (24.10.2026, basiert auf VS Code 1.143.1)
Image-Größe	ca. 300 MB komprimiert
Architekturen	x86-64 (amd64), ARM64
Web-Port intern	8443 (HTTP)
Empfohlener Host-Port	8443:8443
Pflicht-Volume	/volume1/docker/code-server/config:/config
Empfohlenes Workspace-Volume	/volume1/docker:/config/workspace/docker

Umgebungsvariablen

Variable	Beispielwert	Pflicht?	Bedeutung
PUID	1026	Ja	User-ID des NAS-Benutzers (per SSH: id)
PGID	100	Ja	Group-ID (typisch 100 = users auf Synology)
TZ	Europe/Berlin	Empfohlen	Zeitzone des Containers
PASSWORD	sicheres_passwort	Dringend empfohlen	Web-GUI-Passwort; ohne diesen Wert ist der Zugang offen
HASHED_PASSWORD	(Argon2-Hash)	Alternativ zu PASSWORD	Argon2-Hash statt Klartext; hat Vorrang vor PASSWORD
SUDO_PASSWORD	sudo_passwort	Optional	Gibt dem Terminal sudo-Rechte, z. B. für Paketinstallationen
SUDO_PASSWORD_HASH	(Hash)	Optional	Gehashtes sudo-Passwort (Format $typ$salt$hash), hat Vorrang
PROXY_DOMAIN	code.nas.beispiel.de	Optional	Nur für Subdomain-Proxying weiterer Ports (z. B. Entwicklungsserver); für einen normalen Reverse Proxy nicht nötig
DEFAULT_WORKSPACE	/config/workspace	Optional	Startordner im Editor-Explorer
PWA_APPNAME	code-server	Optional	Name beim Installieren als Progressive Web App

Schritt 1: PUID und PGID ermitteln

Die PUID und PGID sorgen dafür, dass Dateien, die der Container anlegt, dem richtigen NAS-Benutzer gehören – ohne passende Werte entstehen Dateien mit fremdem Besitzer, die Ihr NAS-Benutzer später nicht bearbeiten kann. Verbinden Sie sich per SSH mit dem NAS (Anleitung: SSH auf dem Synology NAS aktivieren und verbinden) und führen Sie folgenden Befehl aus:

id

Typische Ausgabe auf einem Synology NAS:

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

Notieren Sie uid (hier: 1026) und gid (hier: 100). Diese Werte tragen Sie in der Compose-Datei als PUID und PGID ein. Verwenden Sie nicht die generischen Standardwerte 1000/1000 – auf Synology sind diese fast immer falsch.

Verifizieren: Die Ausgabe von id zeigt eine uid=-Zeile. Werte außerhalb des Bereichs 1000–1100 für PUID sind auf Synology ungewöhnlich; prüfen Sie in DSM unter Systemsteuerung > Benutzer und Gruppe, welcher Benutzer gemeint ist.

Schritt 2: Ordnerstruktur anlegen

Legen Sie das Verzeichnis über die File Station oder per SSH an, bevor der Container startet. Der Container Manager erwartet existierende Pfade für Bind-Mounts.

mkdir -p /volume1/docker/code-server/config

Der Ordnername muss exakt so lauten (alles kleingeschrieben), da Btrfs und ext4 Groß- und Kleinschreibung unterscheiden. Den Ordner /volume1/docker legt der Container Manager bei der Installation an.

Verifizieren: Per SSH zeigt ls -la /volume1/docker/code-server/ den Ordner config mit Ihrem NAS-Benutzer als Besitzer.

Schritt 3: Compose-Datei erstellen und Projekt anlegen

Öffnen Sie den Container Manager, wechseln Sie zu Projekt und klicken Sie auf Erstellen. Vergeben Sie den Projektnamen code-server und tragen Sie folgende Compose-Konfiguration ein. Passen Sie PUID, PGID, PASSWORD und SUDO_PASSWORD an. Details zum Anlegen von Projekten: Container Manager: Docker-Compose-Projekt anlegen, starten und aktualisieren.

services:
  code-server:
    image: lscr.io/linuxserver/code-server:latest
    container_name: code-server
    environment:
      - PUID=1026
      - PGID=100
      - TZ=Europe/Berlin
      - PASSWORD=sicheres_passwort_aendern
      - SUDO_PASSWORD=sudo_passwort_aendern
      - DEFAULT_WORKSPACE=/config/workspace
      - PWA_APPNAME=code-server
    volumes:
      - /volume1/docker/code-server/config:/config
      - /volume1/docker:/config/workspace/docker
    ports:
      - 8443:8443
    restart: unless-stopped

Das zweite Volume bindet Ihren gesamten Docker-Ordner als /config/workspace/docker ein; alle Compose-Projekte (Dockge, Gitea, Semaphore usw.) sind damit im Editor sichtbar und bearbeitbar. Ist Port 8443 bereits belegt, ändern Sie den Host-Port, z. B. auf 8444:8443. Optionale Variablen wie HASHED_PASSWORD oder PROXY_DOMAIN ergänzen Sie nur bei Bedarf; eine leer gesetzte PROXY_DOMAIN übergibt das Startskript trotzdem als Parameter an code-server.

Verifizieren: Container Manager zeigt das Projekt code-server in der Projektliste mit Status Wird ausgeführt. Im Protokoll-Tab des Containers erscheinen [ls.io-init] done. und eine Zeile mit HTTP server listening on; erst dann ist der Server bereit.

Schritt 4: Erster Login und Passwort-Verifikation

Öffnen Sie im Browser http://<NAS-IP>:8443. Auf dem Anmeldebildschirm geben Sie das in PASSWORD gesetzte Passwort ein.

Nach der Anmeldung erscheint die VS-Code-Oberfläche. Im Explorer ist unter workspace der Ordner docker mit Ihren Compose-Projekten sichtbar.

Wichtig: Ist weder PASSWORD noch HASHED_PASSWORD gesetzt, ist die Instanz ohne Authentifizierung erreichbar. Jeder im lokalen Netz könnte dann das Terminal nutzen und auf alle gemounteten Volumes zugreifen. Stoppen Sie in diesem Fall den Container, tragen Sie PASSWORD in der Compose-Datei ein und erstellen Sie das Projekt neu.

Verifizieren: Die VS-Code-Oberfläche öffnet sich fehlerfrei im Browser. Der Explorer zeigt den Ordner docker, eine vorhandene Compose-Datei lässt sich öffnen und bearbeiten.

Schritt 5: Extension installieren und Terminal testen

Extensions werden unter /config/extensions gespeichert und überleben Container-Neustarts sowie Image-Updates, solange das /config-Volume persistent gemountet bleibt.

Klicken Sie links in der Aktivitätsleiste auf das Extensions-Symbol (oder Strg+Umschalt+X). Suchen Sie eine Extension, z. B. „YAML“ von Red Hat, und klicken Sie auf Install. code-server nutzt dafür die Open-VSX-Registry, nicht den Microsoft-Marketplace. Die Extension wird direkt in /config/extensions gespeichert.

Öffnen Sie danach das Terminal über Terminal > New Terminal. Es läuft im Container als der per PUID/PGID konfigurierte Benutzer. Prüfen Sie den Zugriff auf das eingebundene Volume:

ls /config/workspace/docker

Die Ausgabe listet Ihre Docker-Projektordner. Mit gesetztem SUDO_PASSWORD testen Sie zusätzlich:

sudo apt-get update

Verifizieren: Die installierte Extension erscheint in der Extensions-Liste als Installed. Im Terminal gibt ls /config/workspace/docker Ihre Compose-Projektordner aus. Nach einem Container-Neustart ist die Extension noch vorhanden – sie liegt persistent im /config-Volume.

Schritt 6: Synology Reverse Proxy für HTTPS einrichten (optional)

Für HTTPS oder Zugriff von außen richten Sie den Synology Reverse Proxy ein: Systemsteuerung > Anmeldeportal > Erweitert > Reverse Proxy, neuen Eintrag erstellen:

• Quell-Protokoll: HTTPS, Port 443
• Quell-Hostname: Ihre Domain (z. B. code.nas.beispiel.de)
• Ziel-Protokoll: HTTP
• Ziel-Hostname: localhost, Port 8443

Wichtig: Wählen Sie im Reiter Benutzerdefinierte Kopfzeile „Erstellen > WebSocket“. Ohne WebSocket-Unterstützung erscheinen Verbindungsabbrüche und die Fehlermeldung „WebSocket connection failed“ in der Browser-Konsole. PROXY_DOMAIN ist dafür nicht nötig.

Verifizieren: Rufen Sie https://code.nas.beispiel.de im Browser auf. Der Login-Bildschirm erscheint mit gültigem HTTPS-Zertifikat (Schloss-Symbol im Browser). Die Browser-Konsole zeigt keine WebSocket-Fehler.

Troubleshooting / Typische Fehler

• Container startet nicht, Port-Konflikt: Port 8443 ist bereits durch einen anderen Dienst belegt. Prüfen Sie Container Manager > Protokoll auf address already in use. Lösung: Host-Port in der Compose-Datei ändern, z. B. 8444:8443.
• Dateien im Editor nicht schreibbar: PUID/PGID stimmen nicht mit dem tatsächlichen NAS-Benutzer überein. Führen Sie per SSH id aus und tragen Sie die korrekten Werte ein. Prüfen Sie mit ls -la /volume1/docker/code-server/, ob der Ordner dem richtigen Benutzer gehört.
• „WebSocket connection failed“ im Browser: Der Synology Reverse Proxy leitet WebSocket-Verbindungen nicht weiter. Lösung: Im Reverse-Proxy-Eintrag unter Benutzerdefinierte Kopfzeile die WebSocket-Option aktivieren.
• Extensions nach Neustart weg: Das /config-Volume ist nicht persistent gemountet. Extensions liegen in /config/extensions – das Volume muss im Compose-Eintrag stets vorhanden sein.
• Passwort wird abgelehnt: In der Listenschreibweise werden Anführungszeichen hinter dem = Teil des Passworts. Setzen Sie bei Sonderzeichen den ganzen Eintrag in Anführungszeichen: - "PASSWORD=mein!Passwort#2026". Nach zu vielen Fehlversuchen greift zudem die Anmeldesperre (siehe FAQ).
• sudo: Berechtigung verweigert: SUDO_PASSWORD wurde nicht gesetzt. Tragen Sie einen Wert ein und erstellen Sie den Container neu.
• Workspace-Ordner im Explorer leer: Das zweite Volume wurde nicht korrekt eingetragen oder der Pfad /volume1/docker existiert nicht. Prüfen Sie per SSH mit ls /volume1/docker und korrigieren Sie den Volume-Eintrag.
• PROXY_DOMAIN gesetzt, code-server lädt nicht: Auch eine leer gesetzte Variable wird als --proxy-domain= übergeben. Entfernen Sie die Zeile ganz, sofern Sie kein Subdomain-Proxying nutzen.
• Ressourcenengpass auf kleinen NAS-Modellen: code-server benötigt mindestens 1 GB RAM. Auf einem NAS mit 2 GB Gesamt-RAM (z. B. DS220+) kann das andere Container verlangsamen. RAM-Nutzung im Container Manager unter Container > Ressourcen beobachten.

Häufige Fragen

Kann ich code-server ohne Reverse Proxy betreiben?

Ja. Direkt über http://nas-ip:8443 ist code-server ohne HTTPS erreichbar. Im lokalen Netz ist das vertretbar, sofern PASSWORD gesetzt ist. Für den Zugriff von außen ist ein Reverse Proxy mit TLS Pflicht, da andernfalls Passwort und Terminalausgaben im Klartext übertragen werden.

Bleiben installierte Extensions nach einem Image-Update erhalten?

Ja. Alle Extensions liegen unter /config/extensions innerhalb des persistenten /config-Volumes. Solange dieses Volume gemountet bleibt, überleben Extensions sowohl Container-Neustarts als auch das Hochziehen auf eine neue Image-Version über Container Manager > Projekt > Aktion > Neuerstellen. Im Test des Updates von 4.140.0-ls368 auf 4.141.0-ls369 mit dieser Compose-Datei blieb eine vorher installierte Extension erhalten, die Anmeldung mit dem Passwort aus PASSWORD funktionierte weiter, ein falsches Passwort führte zurück zur Anmeldeseite, und der eingebundene Docker-Ordner war unverändert sichtbar. Version 4.141.0 bringt VS Code 1.141.0 und die neue Option --enable-remote-storage, mit der code-server den Arbeitsbereichs-Zustand auf dem Server statt im Browser speichert.

4.141.1 aktualisiert laut Release Notes das mitgelieferte Node.js auf 24.22.1 und schließt damit eine Lücke im Brotli-Decoder (CVE-2026-111497); komprimierte Request-Bodies lehnt code-server seither ab. 4.143.1 bringt VS Code 1.143.1. Im Test des Updates von 4.141.0-ls369 auf 4.143.1-ls373 am 26.10.2026 blieb die vorher installierte YAML-Extension erhalten, code-server --version meldete 4.143.1 mit Code 1.143.1, die Anmeldung mit dem Passwort aus PASSWORD funktionierte, ein falsches Passwort führte zurück zur Anmeldeseite, und der eingebundene Docker-Ordner war unverändert sichtbar.

Wie sichere ich code-server stärker ab als mit einem Klartext-Passwort?

Setzen Sie statt PASSWORD die Variable HASHED_PASSWORD auf einen Argon2-Hash. Die code-server-Dokumentation erzeugt ihn mit echo -n "passwort" | npx argon2-cli -e; der Hash beginnt mit $argon2. In der Compose-Datei verdoppeln Sie jedes $ zu $$, sonst interpretiert Compose es als Variable. Zusätzlich lässt sich ein Reverse Proxy mit OAuth2-Anmeldung vorschalten. Fehlgeschlagene Anmeldungen begrenzt code-server bereits auf 2 pro Minute und 12 pro Stunde.

Kann ich mehrere code-server-Instanzen betreiben?

Ja. Legen Sie in der Compose-Datei mehrere Services mit unterschiedlichen Container-Namen, Port-Mappings und /config-Volume-Pfaden an – z. B. eine Instanz pro Projekt oder Benutzer. Jede Instanz hat ihre eigenen Extensions, Settings und Workspace-Konfiguration.

Funktioniert die Git-Integration in code-server?

Ja. Git ist im linuxserver.io-Image vorinstalliert. Die eingebaute Source-Control-Ansicht von VS Code funktioniert vollständig. Wenn Sie eine Gitea-Instanz auf demselben NAS betreiben, erreichen Sie das Git-Repository direkt aus dem Editor über die interne Docker-IP oder den NAS-Hostnamen.

Wie viel RAM benötigt code-server?

Die code-server-Dokumentation empfiehlt mindestens 1 GB RAM und 2 CPU-Kerne. Auf einem NAS mit 2 GB Gesamt-RAM (z. B. DS220+) kann code-server andere Container merklich verlangsamen. Beobachten Sie die RAM-Nutzung im Container Manager unter Container > Ressourcen. Auf Modellen mit 4 GB oder mehr läuft code-server erfahrungsgemäß problemlos neben anderen Diensten.

Fazit

code-server auf dem Synology NAS verwandelt das NAS in eine browser-gestützte Entwicklungsumgebung. Dank des linuxserver.io-Images und PUID/PGID-Support fügt sich der Container sauber in die bestehende NAS-Rechteverwaltung ein – Dateien gehören dem richtigen Benutzer, Extensions bleiben persistent, und der gemountete Docker-Ordner macht alle Compose-Projekte direkt editierbar. Der Vorteil gegenüber SSH: eine vollwertige IDE mit Syntax-Highlighting, Git-Integration und Extension-Ökosystem, erreichbar von jedem Browser aus. Als Steuerzentrale für Compose-Dateien, Skripte und Git-Commits direkt auf dem NAS spart code-server laufende Cloud-Kosten. Beachten Sie: Wer Zugriff auf die Oberfläche hat, hat über das Terminal Zugriff auf alle eingebundenen Ordner.

Weiterführende Anleitungen und Quellen

• Dockge auf dem Synology NAS installieren: Docker-Compose-Stacks einfach verwalten – Compose-Projekte visuell verwalten, ideal als Ergänzung zu code-server
• Gitea mit Docker: eigener Git-Server als GitHub-Alternative – Git-Repositories auf dem NAS selbst hosten, direkt aus code-server erreichbar
• Semaphore UI auf dem Synology NAS: Ansible-Automatisierung per Web-GUI – in code-server geschriebene Playbooks direkt ausführen
• Container Manager: Docker-Compose-Projekt anlegen, starten und aktualisieren

Offizielle Dokumentation: LinuxServer.io – docker-code-server | GitHub – linuxserver/docker-code-server | GitHub – coder/code-server (Upstream)