VS Code Server Setup Guide

Phase 6: Remote Development Environment

Stand: 25. Oktober 2025
Version: 1.0
Ziel: Remote-Entwicklung über Browser ohne lokalen VS Code

---

🎯 ÜBERSICHT

VS Code Server (code-server) ermöglicht: - ✅ VS Code im Browser (keine Desktop-Installation nötig) - ✅ Entwicklung von überall (über Cloudflare Tunnel) - ✅ Zugriff auf Docker-Container direkt - ✅ Volle Git-Integration - ✅ Extensions wie im Desktop VS Code

---

📦 INSTALLATION

1. Code-Server starten

# Im solarlog_20251022 Verzeichnis:
./deployment/scripts/start-code-server.sh

# Oder manuell:
docker compose -f docker-compose.code-server.yml up -d

2. Zugriff prüfen

Lokal (ohne Tunnel):

# Browser öffnen:
open http://localhost:8443

# Password: solarlog_code_2024

3. Cloudflare Tunnel konfigurieren

Tunnel Config aktualisieren:

# Backup erstellen
cp deployment/cloudflare/tunnel-config.yml deployment/cloudflare/tunnel-config.yml.backup

# Neue Config mit Code-Server kopieren
cp deployment/cloudflare/tunnel-config-with-code-server.yml deployment/cloudflare/tunnel-config.yml

DNS Route hinzufügen:

# DNS Entry für code.karma.organic
cloudflared tunnel route dns solarlog-tunnel code.karma.organic

Tunnel neu starten:

# Bestehenden Tunnel stoppen
pkill -f cloudflared

# Neu starten mit aktualisierter Config
nohup cloudflared tunnel --config deployment/cloudflare/tunnel-config.yml run solarlog-tunnel &

4. Remote-Zugriff testen

# Browser öffnen:
open https://code.karma.organic

# Login: solarlog_code_2024

---

🔧 KONFIGURATION

Password ändern

Option 1: Umgebungsvariable (empfohlen)

# .env Datei erstellen:
echo "CODE_SERVER_PASSWORD=dein_sicheres_passwort" >> .env

# Restart
docker compose -f docker-compose.code-server.yml restart

Option 2: Config-Datei editieren

# Config editieren:
nano deployment/code-server/config.yaml

# Zeile ändern:
password: dein_sicheres_passwort

# Volume in Container kopieren:
docker cp deployment/code-server/config.yaml solarlog-code-server:/home/coder/.config/code-server/config.yaml

# Restart
docker compose -f docker-compose.code-server.yml restart

Extensions installieren

Methode 1: UI (empfohlen) 1. Code-Server im Browser öffnen 2. Extensions Icon (links) → Search 3. Extension suchen und installieren

Methode 2: CLI

# In Container gehen:
docker exec -it solarlog-code-server bash

# Extension installieren:
code-server --install-extension ms-python.python
code-server --install-extension ms-azuretools.vscode-docker
code-server --install-extension eamodio.gitlens

# Exit
exit

Methode 3: Batch-Install

# Alle empfohlenen Extensions installieren:
docker exec -it solarlog-code-server bash -c '
  code-server --install-extension ms-python.python
  code-server --install-extension ms-python.vscode-pylance
  code-server --install-extension ms-azuretools.vscode-docker
  code-server --install-extension eamodio.gitlens
  code-server --install-extension redhat.vscode-yaml
  code-server --install-extension esbenp.prettier-vscode
  code-server --install-extension ckolkman.vscode-postgres
  code-server --install-extension yzhang.markdown-all-in-one
'

Empfohlene Extensions: Siehe deployment/code-server/extensions.txt

Workspace Settings

Settings Sync (Optional):

// In code-server: Settings → Settings Sync
{
  "settingsSync.enabled": true,
  "settingsSync.keybindingsPerPlatform": false
}

Workspace Settings:

// .vscode/settings.json (bereits im Projekt):
{
  "python.defaultInterpreterPath": "/usr/local/bin/python",
  "python.linting.enabled": true,
  "python.linting.pylintEnabled": true,
  "editor.formatOnSave": true,
  "files.trimTrailingWhitespace": true,
  "[python]": {
    "editor.defaultFormatter": "ms-python.python"
  }
}

---

🐳 DOCKER-INTEGRATION

Docker-Befehle im Terminal

# Im code-server Terminal (unten):
docker ps                                # Container auflisten
docker logs -f solarlog-backend          # Backend Logs
docker compose restart backend           # Backend neu starten
docker exec -it solarlog-postgres psql -U solarlog solarlog_db  # PostgreSQL

Docker Extension nutzen

1. Docker Icon (links) → Container view
2. Rechtsklick auf Container → Logs / Restart / Shell

---

🔒 SECURITY

Cloudflare Access (Optional)

Empfohlen für Production!

# Cloudflare Zero Trust konfigurieren:
# 1. Cloudflare Dashboard → Access → Applications
# 2. Add Application:
#    - Name: SolarLog Code-Server
#    - Domain: code.karma.organic
#    - Session Duration: 24h
# 3. Policy:
#    - Rule: Emails ending in @yourdomain.com
#    - Action: Allow

# Dann: code-server Password deaktivieren (Optional)
# Config: auth: none

Firewall Rules

# Port 8443 nur für Cloudflare IPs öffnen (Pi 5):
sudo ufw allow from 173.245.48.0/20 to any port 8443
sudo ufw allow from 103.21.244.0/22 to any port 8443
# ... (siehe Cloudflare IP Ranges)

---

📊 MONITORING

Health Check

# Container Status:
docker ps --filter name=solarlog-code-server

# Health:
docker inspect solarlog-code-server | jq '.[0].State.Health'

# Logs:
docker logs -f solarlog-code-server

Resource Usage

# Stats:
docker stats solarlog-code-server

# Disk Usage:
docker system df -v | grep code-server

---

🐛 TROUBLESHOOTING

Problem: Code-Server startet nicht

Lösung 1: Logs prüfen

docker logs solarlog-code-server

Lösung 2: Permissions

# User ID prüfen:
echo $UID

# Falls falsch: docker-compose.code-server.yml editieren:
user: "1000:1000"  # Deine UID/GID eintragen

Problem: Extensions fehlen nach Restart

Ursache: Volume nicht persistent

Lösung:

# Volumes prüfen:
docker volume ls | grep code-server

# Sollte existieren:
# solarlog-code-server-extensions
# solarlog-code-server-config

Problem: Keine Docker-Befehle im Terminal

Lösung: Docker Socket Permissions

# User zur docker Gruppe hinzufügen (Host):
sudo usermod -aG docker $USER

# Oder: Socket Permissions im Container:
docker exec -u root solarlog-code-server chmod 666 /var/run/docker.sock

Problem: WebSocket-Fehler (Cloudflare)

Lösung: Tunnel Config

# tunnel-config.yml:
- hostname: code.karma.organic
  service: http://localhost:8443
  originRequest:
    disableChunkedEncoding: false  # ⬅️ WICHTIG für WebSockets!

---

🚀 ADVANCED USAGE

Remote SSH (Alternative zu Browser)

# VS Code Desktop → Remote-SSH Extension
# Host: code.karma.organic:22 (falls SSH exposed)

# Oder: SSH Tunnel über Cloudflare:
cloudflared access ssh --hostname code.karma.organic

GitHub Copilot (Optional)

Voraussetzung: GitHub Copilot Subscription

# Extension installieren:
code-server --install-extension github.copilot

# Login:
# 1. Extensions → GitHub Copilot → Sign in
# 2. Device Code eingeben
# 3. GitHub Authorization

Multi-User Setup (Future)

# docker-compose.code-server.yml:
# Mehrere code-server Instanzen für verschiedene User:
code-server-dev1:
  image: codercom/code-server:latest
  ports:
    - "8443:8080"
  environment:
    PASSWORD: dev1_password

code-server-dev2:
  image: codercom/code-server:latest
  ports:
    - "8444:8080"
  environment:
    PASSWORD: dev2_password

# Cloudflare Tunnel:
# - hostname: code-dev1.karma.organic → localhost:8443
# - hostname: code-dev2.karma.organic → localhost:8444

---

� TROUBLESHOOTING (Production-Tested)

Issue 1: Container startet nicht (Restarting)

Symptom:

docker ps | grep code-server
# STATUS: Restarting (1)

Logs:

docker logs solarlog-code-server
# sudo: The "no new privileges" flag is set
# fixuid: fixuid is not running as root

Root Cause: security_opt: no-new-privileges:true verhindert sudo/fixuid

✅ Lösung: Security-Optionen auskommentieren in docker-compose.code-server.yml:

services:
  code-server:
    # user: "${UID:-1000}:${GID:-1000}"      # ← Auskommentiert
    # security_opt:                          # ← Auskommentiert
    #   - no-new-privileges:true

Container neu starten:

docker compose -f docker-compose.code-server.yml restart

---

Issue 2: EACCES Permission Errors

Symptom:

docker logs solarlog-code-server
# [error] EACCES: permission denied, mkdir '/home/coder/.config/code-server'

Root Cause: Docker Volumes haben falsche Permissions

✅ Lösung: Lokale Directories statt Docker Volumes:

# Directories erstellen
mkdir -p deployment/code-server/data/{config,extensions}

docker-compose.code-server.yml anpassen:

volumes:
  # Alt (nicht verwenden):
  # - code_server_config:/home/coder/.config

  # Neu (funktioniert):
  - ./deployment/code-server/data/config:/home/coder/.config
  - ./deployment/code-server/data/extensions:/home/coder/.local/share/code-server

Container neu starten:

docker compose -f docker-compose.code-server.yml down
docker compose -f docker-compose.code-server.yml up -d

---

Issue 3: WebSocket-Fehler im Browser

Symptom:

ERR Cannot read properties of undefined (reading 'response')
TypeError: Cannot read properties of undefined (reading 'response')
    at tat.complete (https://code.karma.organic/.../workbench.js:2239:937)

Root Cause: Falsche Cloudflare Tunnel WebSocket-Config

✅ Lösung: tunnel-config.yml korrigieren:

- hostname: code.karma.organic
  service: http://localhost:8443
  originRequest:
    noTLSVerify: true
    connectTimeout: 30s
    keepAliveTimeout: 90s
    keepAliveConnections: 100
    noHappyEyeballs: true
    # ⚠️ KRITISCH für WebSockets:
    disableChunkedEncoding: true   # ← Muss TRUE sein!
    http2Origin: false              # ← HTTP/1.1 verwenden

Tunnel neu starten:

pkill -f cloudflared
cd /Users/gm/Documents/XCITE_DEV_DOCKER/solarlog_20251022
nohup cloudflared tunnel --config deployment/cloudflare/tunnel-config.yml run solarlog-tunnel > logs/cloudflared.log 2>&1 &

Testen:

# Cache leeren, dann neu laden:
# Chrome/Edge: Cmd + Shift + R (macOS) / Ctrl + Shift + R (Linux/Windows)
# Oder: Inkognito/Privat-Tab öffnen

---

Issue 4: 502 Bad Gateway

Prüfen:

1. Container läuft?

   docker ps | grep code-server
   # Sollte "Up (healthy)" zeigen
   

2. Port erreichbar?

   curl -I http://localhost:8443
   # Sollte "HTTP/1.1 302 Found" zurückgeben
   

3. Tunnel aktiv?

   ps aux | grep cloudflared
   tail -20 logs/cloudflared.log
   # Sollte "Registered tunnel connection" zeigen
   

---

�📋 CHECKLISTE

Post-Installation: - [ ] Code-Server läuft (http://localhost:8443) - [ ] Cloudflare Tunnel konfiguriert - [ ] DNS Route hinzugefügt (code.karma.organic) - [ ] Remote-Zugriff funktioniert (https://code.karma.organic) - [ ] Password geändert (sicheres Passwort!) - [ ] Extensions installiert (siehe extensions.txt) - [ ] Docker-Integration funktioniert - [ ] Git-Integration funktioniert - [ ] Workspace Settings konfiguriert - [ ] Troubleshooting Issues 1-3 durchgearbeitet ✅

---

🔗 LINKS

• code-server Docs
• Cloudflare Tunnel Docs
• Open VSX Registry

---

See also: - PROJECT_STATUS_ROADMAP.md - Phase 6 Details - deployment/cloudflare/ - Tunnel Configuration - deployment/code-server/extensions.txt - Recommended Extensions