code-server: VS Code im Browser auf dem eigenen Server

VS Code im Browser, vom Tablet aus, vom fremden Rechner, ohne lokale Einrichtung – das ist der verlockende Teil. Der unbequeme: Wer sich dort anmeldet, bekommt ein Terminal auf deinem Server. Genau deshalb ist dieses Tutorial zur Hälfte ein Sicherheits-Tutorial.

Was bauen wir?

Wir betreiben code-server 4.141.0 (basiert auf VS Code 1.141.0) hinter Traefik, erreichbar über HTTPS und geschützt durch zwei unabhängige Schlösser: BasicAuth in Traefik und das eigene Passwort von code-server. Dazu bauen wir ein eigenes Image mit der Werkzeugkette, die du wirklich brauchst – das offizielle Image bringt nämlich keine mit.

Am Ende kannst du im Browser eine Datei bearbeiten, sie im integrierten Terminal ausführen und das Ergebnis abrufen. Erweiterungen überleben den Neustart, der Container läuft ohne Capabilities und kann sich intern keine Root-Rechte mehr holen.

Voraussetzungen

• Traefik als Reverse Proxy mit funktionierendem Let’s-Encrypt-Resolver und einer Domain, die auf den Server zeigt
• BasicAuth aus dem Traefik-Härtungs-Tutorial – wir benutzen die Middleware hier direkt
• Mindestens 2 GB freier Arbeitsspeicher. Mit einer offenen Datei und aktiver Python-Erweiterung braucht der Container 500 bis 650 MB, unter Last mehr – das Limit setzen wir auf 2 GB
• Etwa 6 GB Plattenplatz: Das Basis-Image ist 1,51 GB groß, unser erweitertes 1,99 GB

Schritt für Schritt

Schritt 1: Verzeichnisse anlegen und den Passwort-Hash erzeugen

code-server läuft im Container als Benutzer mit der UID 1000. Damit er in die gemounteten Ordner schreiben kann, müssen sie ihm auch gehören:

mkdir -p /opt/code-server/{config,local,projekte}
chown -R 1000:1000 /opt/code-server
cd /opt/code-server

Die drei Ordner haben klar getrennte Aufgaben: config enthält die Konfiguration, local die installierten Erweiterungen und den Editor-Zustand, projekte deinen Code. Nur der dritte enthält Dinge, die du nicht neu erzeugen kannst.

Jetzt der Passwort-Hash. code-server versteht Argon2-Hashes, und Debian bringt das passende Werkzeug mit:

apt-get install -y argon2
echo -n "DEIN_CODE_SERVER_PASSWORT" | argon2 "$(openssl rand -base64 12)" -e -id -k 65540 -t 3 -p 4

$argon2id$v=19$m=65540,t=3,p=4$XXXXXXXXXXXXXXXXXXXXXXXX$XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

openssl rand liefert das Salz, -id wählt die empfohlene Argon2id-Variante, -k 65540 sind rund 64 MB Speicherkosten pro Prüfung. Das macht Rateversuche teuer.

Den Hash trägst du in code-servers eigene Konfigurationsdatei ein, nicht in eine Umgebungsvariable:

# /opt/code-server/config/code-server/config.yaml
bind-addr: 0.0.0.0:8080
auth: password
hashed-password: "$argon2id$v=19$m=65540,t=3,p=4$DEIN$HASH"
cert: false
disable-telemetry: true
disable-update-check: true
disable-workspace-trust: true

mkdir -p config/code-server   # Datei dort ablegen
chown -R 1000:1000 config

Warum die Datei und nicht environment:? Weil Docker Compose jedes $ in Umgebungsvariablen als Variablenbeginn liest und dir den Hash zerlegt – ein Fehler, den man erst beim Login bemerkt. Details dazu unten bei „Wenn es nicht funktioniert". cert: false ist richtig, weil Traefik das TLS übernimmt. disable-workspace-trust erspart dir bei jedem Ordner die Rückfrage „Vertraust du den Autoren?" – auf einem Server, auf dem nur dein eigener Code liegt, ist das nur Klickarbeit.

Schritt 2: Ein eigenes Image, weil das offizielle leer ist

Das ist der Punkt, an dem die meisten Anleitungen aufhören und der Ärger anfängt. Sieh dir an, was im offiziellen Image steckt:

docker run --rm --entrypoint sh codercom/code-server:4.141.0 \
  -c 'for c in git curl python3 node gcc make; do printf "%-8s %s\n" $c "$(command -v $c || echo FEHLT)"; done'

git      /usr/bin/git
curl     /usr/bin/curl
python3  FEHLT
node     FEHLT
gcc      FEHLT
make     FEHLT

Das Image enthält den Editor, sonst nichts. Eine .py-Datei bekommt Syntaxhervorhebung, aber python3 app.py im Terminal antwortet mit bash: python3: command not found. Deshalb bauen wir ein abgeleitetes Image mit genau der Werkzeugkette, die du brauchst:

# /opt/code-server/Dockerfile
FROM codercom/code-server:4.141.0

USER root
RUN apt-get update \
 && apt-get install -y --no-install-recommends \
      python3 python3-venv python3-pip build-essential jq \
 && rm -rf /var/lib/apt/lists/*
USER coder

Tausch die Paketliste gegen das aus, womit du arbeitest – nodejs npm für JavaScript, golang-go für Go. Das USER coder am Ende ist wichtig: Sonst startet der Editor als root.

Schritt 3: Der Compose-Stack

Zuerst den BasicAuth-Hash für Traefik erzeugen:

docker run --rm httpd:2.4-alpine htpasswd -nbB DEIN_BENUTZER DEIN_BASICAUTH_PASSWORT

DEIN_BENUTZER:$2y$05$XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# /opt/code-server/compose.yaml
services:
  code-server:
    build: .
    image: serverkueche/code-server:4.141.0
    container_name: code-server
    restart: unless-stopped
    user: "1000:1000"
    environment:
      TZ: Europe/Berlin
    volumes:
      - ./config:/home/coder/.config
      - ./local:/home/coder/.local
      - ./projekte:/home/coder/projekte
    command: ["/home/coder/projekte"]
    cap_drop: [ALL]
    security_opt:
      - no-new-privileges:true
    mem_limit: 2g
    pids_limit: 512
    networks: [proxy]
    labels:
      - traefik.enable=true
      - traefik.http.routers.code.rule=Host(`DEINE_DOMAIN`)
      - traefik.http.routers.code.entrypoints=websecure
      - traefik.http.routers.code.tls.certresolver=le
      - traefik.http.routers.code.middlewares=code-auth@docker
      - traefik.http.middlewares.code-auth.basicauth.users=DEIN_BENUTZER:$$2y$$05$$DEIN$$HASH
      - traefik.http.services.code.loadbalancer.server.port=8080

networks:
  proxy:
    external: true

Vier Zeilen verdienen eine Erklärung, weil sie hier mehr bewirken als üblich:

• user: "1000:1000" – der Editor läuft nicht als root, und die Dateien in projekte gehören danach dir und nicht root.
• cap_drop: [ALL] – code-server braucht keine einzige Linux-Capability. Editor, Terminal und Erweiterungen laufen damit vollständig.
• no-new-privileges:true – die schärfste Zeile. Das offizielle Image enthält /etc/sudoers.d/nopasswd mit coder ALL=(ALL) NOPASSWD:ALL; ohne diesen Schalter ist jeder, der ins Terminal kommt, mit einem sudo root im Container. Mit dem Schalter scheitert sudo sauber: sudo: The "no new privileges" flag is set, which prevents sudo from running as root.
• mem_limit: 2g / pids_limit: 512 – ein durchgedrehter Sprachserver oder eine Endlosschleife im Terminal soll den Server nicht mitnehmen.

Schritt 4: Starten und die Schlösser prüfen

cd /opt/code-server && docker compose up -d --build
docker compose logs --tail 6

info  code-server 4.141.0 8b41915d25547e2edd553bab03ea4cbd621f98c5
info  Using user-data-dir /home/coder/.local/share/code-server
info  Using config file /home/coder/.config/code-server/config.yaml
info  HTTP server listening on http://0.0.0.0:8080/
info    - Authentication is enabled
info      - Using hashed-password from /home/coder/.config/code-server/config.yaml
info    - Not serving HTTPS

Die Zeilen fünf und sechs sind die Bestätigung, dass der Hash gelesen wurde. Not serving HTTPS ist korrekt – das macht Traefik.

Jetzt die Gegenprobe von einem anderen Rechner. Ohne Zugangsdaten kommst du nicht einmal bis zum Login-Formular:

curl -s -o /dev/null -w "%{http_code}\n" https://DEINE_DOMAIN/

401

Mit BasicAuth leitet code-server auf seine eigene Anmeldung weiter:

curl -s -o /dev/null -w "%{http_code}\n" -u DEIN_BENUTZER:DEIN_BASICAUTH_PASSWORT https://DEINE_DOMAIN/

302

Genau so soll es sein: zwei Hürden, zwei verschiedene Passwörter. Im Browser siehst du nach dem BasicAuth-Dialog die Anmeldung von code-server:

Schritt 5: Arbeiten – Datei, Terminal, Port

Nach der Anmeldung landest du direkt im Arbeitsverzeichnis, das wir per command: übergeben haben. Öffne eine Datei mit Strg+P:

Der eigentliche Test ist das Terminal – über die Befehlspalette (Strg+Shift+P) und „Terminal: Create New Terminal". Dort startest du dein Programm und rufst es gleich ab:

cd rezepte-api && python3 app.py & sleep 2; curl -s localhost:8000/rezepte | jq .

VS Code erkennt den geöffneten Port automatisch und bietet ihn im Reiter PORTS an. Über einen Reverse Proxy erreichst du diese weitergeleiteten Ports allerdings nicht von außen – sie sind für die Arbeit im Editor gedacht, nicht zum Veröffentlichen.

Ein sudo im Terminal wird jetzt übrigens abgewiesen. Das ist Absicht: Die Werkzeuge, die du brauchst, stecken schon im Image, und alles darüber hinaus gehört in den Dockerfile – nicht in eine Ad-hoc-Installation, die beim nächsten docker compose pull verschwindet.

Schritt 6: Erweiterungen aus Open VSX

code-server benutzt nicht den Marktplatz von Microsoft, sondern Open VSX. Das ist keine Einstellungssache, sondern eine Lizenzfrage: Der offizielle Marktplatz darf nur von Microsofts eigenen Produkten benutzt werden.

Der Alltag ist besser als sein Ruf: Python, Debugger, Docker, GitLens und die verbreiteten Themes sind vorhanden. Was fehlt, sind die Erweiterungen, die Microsoft ausschließlich für VS Code lizenziert – allen voran Pylance, die C#-Erweiterung und Remote-Development. Für Python springt ms-python.python mit dem freien Sprachserver ein.

Erweiterungen lassen sich auch von der Kommandozeile installieren, was sich für ein reproduzierbares Setup lohnt:

docker exec code-server code-server --install-extension ms-python.python

Extension 'ms-python.vscode-python-envs' v1.38.0 was successfully installed.
Extension 'ms-python.debugpy' v2026.6.0 was successfully installed.
Extension 'ms-python.python' v2026.4.0 was successfully installed.

Sie landen im local-Volume und überstehen damit Neustart und Update:

docker compose restart && sleep 10
docker exec code-server code-server --list-extensions

ms-python.debugpy
ms-python.python
ms-python.vscode-python-envs

Wenn es nicht funktioniert

Dein Problem ist nicht dabei? Alle Fehlermeldungen durchsuchen →

Wartung & Backups

Updates laufen über den Image-Tag, und weil wir selbst bauen, sind es zwei Schritte:

cd /opt/code-server
sed -i 's/code-server:4.141.0/code-server:NEUE_VERSION/g' Dockerfile compose.yaml
docker compose up -d --build
docker exec code-server code-server --version

code-server folgt VS Code eng und veröffentlicht häufig – etwa monatlich eine neue Minor-Version. Du musst nicht jede mitnehmen; einmal im Quartal reicht, solange keine Sicherheitsmeldung dazwischen kommt. Denk daran, dass ein Update auch das Basis-Image erneuert und damit die Debian-Pakete aus deinem Dockerfile – das ist erwünscht.

Sichern musst du nur einen der drei Ordner wirklich:

/opt/code-server/projekte/   # dein Code – unersetzlich
/opt/code-server/config/     # config.yaml mit dem Passwort-Hash
/opt/code-server/Dockerfile  # deine Werkzeugkette
/opt/code-server/compose.yaml

local/ mit den Erweiterungen lässt du bewusst weg: Der Ordner wächst mit jeder Erweiterung – mit der Python-Erweiterung sind es rund 60 MB – und ist in zwei Minuten wiederhergestellt, indem du deine Erweiterungsliste durchinstallierst. Halt die Liste stattdessen als Datei im Projekt fest – code-server --list-extensions > extensions.txt – und sichere die mit. Alles zusammen gehört in dein Restic-Backup.

Besser noch: Nutz Git. Der Editor bringt Git mit, und dein Code liegt damit ohnehin doppelt. Auf einem eigenen Forgejo bleibt er dabei im Haus.

Realistischer Aufwand: Nach dem Aufsetzen wenig – ein Update pro Quartal, ein Blick auf den Speicherverbrauch, wenn der Editor träge wird. Der Punkt, der Aufmerksamkeit braucht, ist nicht die Wartung, sondern die Zugangskontrolle: Wechsle beide Passwörter, wenn ein Gerät abhandenkommt, und prüf regelmäßig in den Traefik-Logs, wer sich am BasicAuth versucht hat.