spawner/docs/templates/VCODER_TEMPLATE.md

💻 ESP8266 IDE Template - Vollständige Dokumentation

Übersicht

Das ESP8266 IDE Template (user-template-vcoder) ist eine vollständige Web-basierte Entwicklungsumgebung für ESP8266/Wemos-Mikrocontroller-Projekte. Es kombiniert code-server (VS Code Web IDE) mit PlatformIO für embedded Systems-Entwicklung.

Features

• ✅ Code-Server Web IDE - VS Code im Browser
• ✅ PlatformIO Extension - Embedded Systems Entwicklung
• ✅ C/C++ Tools - cpptools + clangd für Code Completion
• ✅ Workspace Persistierung - Projekte bleiben erhalten
• ✅ PlatformIO Cache - Toolchains werden gecacht
• ✅ Port 8080 - Standardisiert für Spawner Integration
• ✅ Authentication deaktiviert - Spawner JWT übernimmt Schutz

---

Architektur

High-Level Diagramm

Browser Request
     ↓
code-server Web IDE (Port 8080)
     ↓
     ├─ /home/coder/project (Workspace - Volume)
     ├─ /home/coder/.platformio (Cache - Volume)
     └─ Extensions (cpptools, PlatformIO IDE, clangd)
     ↓
Persistente Speicherung (Docker Volumes)

Komponenten

code-server:

• VS Code Server im Browser
• Port 8080
• --auth=none (Spawner JWT übernimmt den Schutz)
• Automatische Extension-Installation

PlatformIO:

• Venv unter /home/coder/.platformio/penv
• Unterstützt ESP8266, Wemos D1 Mini, etc.
• Toolchains werden gecacht für schnelle Builds

Extensions:

• cpptools (Microsoft C/C++) - IntelliSense, Debugging
• platformio-ide (PlatformIO IDE) - Build, Upload, Monitor
• clangd (LLVM) - C/C++ Language Server

Volumes (Persistent):

• /home/coder/project → Workspace + Projekte
• /home/coder/.platformio → Toolchains, Dependencies

---

Installation & Setup

Schritt 1: Template in .env registrieren

Bearbeite .env und füge das vcoder Template hinzu:

# .env
USER_TEMPLATE_IMAGES="user-template-01:latest;user-template-02:latest;user-template-next:latest;user-template-dictionary:latest;user-template-vcoder:latest"

Wichtig: Nur hier definierte Templates werden von bash install.sh gebaut!

Schritt 2: Metadaten in templates.json aktualisieren

Das Template ist bereits in templates.json registriert:

{
  "type": "vcoder",
  "image": "user-template-vcoder:latest",
  "display_name": "💻 ESP8266 IDE",
  "description": "Web-IDE mit PlatformIO für ESP8266/Wemos Entwicklung"
}

Schritt 3: Build & Deploy

# Alle Templates bauen (inkl. vcoder)
# Das buildiert automatisch user-template-vcoder/
bash install.sh

# Docker Compose neu starten
docker-compose up -d --build

⚠️ Build-Zeit: Der vcoder-Build kann 5-10 Minuten dauern (Extensions werden von GitHub geladen: ~60MB).

---

Workspace Management

Erste Verwendung

Wenn ein Benutzer das Template wählt:

1. Spawner erstellt Container mit user-template-vcoder:latest
2. Mountet zwei Volumes:
   • /data/users/{user_id}/vcoder/workspace → /home/coder/project
   • /data/users/{user_id}/vcoder/platformio → /home/coder/.platformio
3. code-server startet auf Port 8080
4. User erhält Zugang via https://coder.domain.com/{user-slug}
5. Workspace ist leer (Benutzer erstellt neue Projekte)

PlatformIO Projekt erstellen

Im IDE:

1. View → Command Palette (Ctrl+Shift+P)
2. PlatformIO: Create Project
3. Wähle Board (ESP8266, Wemos D1 Mini, etc.)
4. Wähle Speicherort (z.B. /home/coder/project/my-esp8266-project)
5. PlatformIO initialiert platformio.ini + src/main.cpp

Bestehendes Projekt importieren

# Wenn ein Git-Repo vorhanden ist:
cd /home/coder/project
git clone <repo-url>
cd <project-name>
# PlatformIO erkennt platformio.ini automatisch

---

Build & Upload

Build im Terminal

cd /home/coder/project/my-project
pio run -e <ENVIRONMENT>

Verfügbare Environments (Beispiele):

• esp8266 - Generischer ESP8266
• d1_mini - Wemos D1 Mini
• d1_mini_lite - Wemos D1 Mini Lite

Upload zur Hardware

# Lokale Verbindung (wenn Host über USB angebunden)
pio run -e d1_mini -t upload

Hinweis: Upload funktioniert nur wenn der Host USB-Zugriff hat. Für Remote-Uploading externe Tools nutzen.

Serial Monitor

pio device monitor -e d1_mini
# CTRL+] zum Beenden

---

Datapersistierung

Docker Volumes

Zwei Volumes pro User:

1. Workspace Volume:

   • Host: /data/users/{user_id}/vcoder/workspace
   • Container: /home/coder/project
   • Enthält: Benutzer-Projekte, Code-Dateien

2. PlatformIO Cache Volume:

   • Host: /data/users/{user_id}/vcoder/platformio
   • Container: /home/coder/.platformio
   • Enthält: Toolchains (~200MB), Abhängigkeiten, Cache

Automatische Konfiguration

Das Backend (container_manager.py) mountet Volumes automatisch:

if container_type == 'vcoder':
    data_path = f"/data/users/{user_id}/vcoder"
    volumes = {
        f"{data_path}/workspace": {'bind': '/home/coder/project', 'mode': 'rw'},
        f"{data_path}/platformio": {'bind': '/home/coder/.platformio', 'mode': 'rw'},
    }

Persistierungs-Verhalten

• ✅ Projekte bleiben nach Container-Neustart erhalten
• ✅ Toolchains werden nicht erneut heruntergeladen (Cache)
• ✅ Extensions bleiben erhalten
• ✅ VS Code Settings bleiben erhalten

Manuelles Testen

# Container starten
docker run -v /data/users/123/vcoder/workspace:/home/coder/project \
           -v /data/users/123/vcoder/platformio:/home/coder/.platformio \
           -p 8080:8080 user-template-vcoder:latest

# Dateistruktur prüfen
ls -la /data/users/123/vcoder/workspace/
ls -la /data/users/123/vcoder/platformio/

# Container stoppen und neustart
docker stop <container-id>
docker start <container-id>

# Daten sollten noch da sein!

---

Sicherheit

JWT-Cookie Validierung

Das vcoder-Template ist geschützt durch Spawner JWT-Token:

1. HttpOnly Cookie spawner_token wird vom Spawner gesetzt
2. Traefik validiert den Cookie vor Request-Weiterleitung
3. code-server läuft mit --auth=none (Vertrauen auf Traefik-Auth)

How It Works

User Login → Spawner JWT-Cookie
   ↓
Browser sendet Cookie bei jedem Request
   ↓
Traefik validiert Cookie
   ↓
Gültig? → code-server erhält Request
Ungültig? → 403 Forbidden (Traefik-Level)

Sicherheits-Features

• ✅ HttpOnly Cookies - JavaScript kann Token nicht auslesen
• ✅ Secure Flag - Nur über HTTPS übertragen
• ✅ SameSite=Lax - CSRF-Schutz
• ✅ Token Expiration - Standard: 1 Stunde (konfigurierbar)
• ✅ code-server --auth=none - Vertraut auf Traefik-Layer

Isolation

• ✅ Jeder User hat eigenen Container
• ✅ Workspace-Volumes sind pro User isoliert
• ✅ Keine Zugriff auf Docker Socket
• ✅ Resource Limits (CPU/RAM) via container_manager.py

---

Ports & Networking

Port-Nutzung

Port	Service	Beschreibung
8080	code-server	Web IDE
8008	PIO Home Proxy	Über socat-Tunnel
9009	PIO Home (intern)	Von PlatformIO

socat Tunnel

Das Entrypoint-Script startet einen socat-Tunnel:

socat TCP-LISTEN:8008,reuseaddr,fork TCP:localhost:9009 &

Dies ermöglicht PlatformIO Home auf Port 8008 zu erreichbar (intern läuft es auf 9009).

Traefik Integration

Spawner konfiguriert automatisch:

• Host: coder.domain.com
• PathPrefix: /{user-slug}-vcoder
• StripPrefix Middleware: Entfernt Prefix bevor Request zum Container
• Port: 8080

---

Performance & Ressourcen

Empfehlungen

• RAM: 512 MB minimum (Default aus .env)
• CPU: 0.5 CPU minimum (Default aus .env)
• Workspace Size: < 1 GB empfohlen für schnelle Sync
• PlatformIO Cache: ~200 MB (einmalig beim ersten Build)

Resource Limits

In .env konfigurierbar:

DEFAULT_MEMORY_LIMIT=512m      # RAM pro Container
DEFAULT_CPU_QUOTA=50000        # 0.5 CPU = 50000 micro-cpu units

Skalierung für größere Projekte

Wenn Projekte wachsen:

# .env anpassen
DEFAULT_MEMORY_LIMIT=1024m     # 1 GB
DEFAULT_CPU_QUOTA=100000       # 1 CPU full

---

Monitoring & Debugging

Logs anschauen

# Live Logs des Containers
docker logs -f user-<slug>-vcoder-<user_id>

# Beispiel Log Output:
# [SPAWNER] Creating vcoder container...
# [SPAWNER] Volumes für vcoder:
# [SPAWNER]   /data/users/123/vcoder/workspace -> /home/coder/project
# [SPAWNER]   /data/users/123/vcoder/platformio -> /home/coder/.platformio

IDE Access prüfen

# Teste Erreichbarkeit
curl -k https://coder.domain.com/user-slug-vcoder/

# Sollte HTML von code-server zurückgeben

Workspace-Status

# Im Container prüfen
docker exec <container-id> ls -la /home/coder/project/

# Projekte auflisten
docker exec <container-id> find /home/coder/project -name "platformio.ini"

PlatformIO Status

# Boards auflisten
docker exec <container-id> pio boards | head -20

# Installed Platforms
docker exec <container-id> pio platform list

# Cache-Status
docker exec <container-id> du -sh /home/coder/.platformio/

---

Troubleshooting

Problem: "IDE lädt nicht / 503 Fehler"

Mögliche Ursachen:
1. Container startet nicht
2. Port 8080 wird nicht exponiert
3. Traefik erkennt Container nicht
4. Extensions werden noch heruntergeladen

Lösung:
docker logs user-<slug>-vcoder-<id>
docker inspect user-<slug>-vcoder-<id> | grep State

Wenn Extensions installiert werden:
Warte 2-3 Minuten für erste IDE-Erreichbarkeit

Problem: "Workspace ist leer nach Neustart"

Mögliche Ursachen:
1. Volume nicht korrekt gemountet
2. Pfad-Berechtigungen falsch

Lösung:
docker inspect <container-id> | grep -A10 Mounts

Sollte zeigen:
"Mounts": [
  {
    "Type": "bind",
    "Source": "/data/users/123/vcoder/workspace",
    "Destination": "/home/coder/project"
  }
]

Problem: "PlatformIO Build fehlgeschlagen"

Häufige Fehler:
1. Toolchain nicht heruntergeladen
2. platformio.ini Fehler
3. Missing Dependencies

Lösung im Terminal:
pio run -e d1_mini -v  # Verbose output
pio platform install espressif8266
pio lib list

Problem: "Code Completion funktioniert nicht"

Ursache: cpptools/clangd-Extension wird noch heruntergeladen

Lösung:
1. IDE neuladen (F5)
2. View → Extensions - cpptools sollte installiert sein
3. Falls nicht: Command Palette → Install Extension "ms-vscode.cpptools"
4. Warte bis Symbol "[Installing]" weg ist

Problem: "Build dauert sehr lange beim ersten Mal"

Das ist normal! Beim ersten Build:
1. Toolchains werden heruntergeladen (~50-200 MB je nach Board)
2. Dependencies werden kompiliert
3. Cache wird aufgebaut

Nächste Builds sind viel schneller (Cache wird reused).

Symptom:
- Erste Build: 2-5 Minuten
- Nächste Builds: 10-30 Sekunden

---

Entwicklungs-Workflow

Neue Projekte

1. IDE öffnen (https://coder.domain.com/...)
2. Terminal: Command Palette → PlatformIO: Create Project
3. Board auswählen (z.B. "Wemos D1 Mini")
4. Speicherpfad: /home/coder/project/mein-projekt
5. platformio.ini + src/main.cpp werden generiert
6. Beginne mit Code-Schreiben!

Bestehendes Projekt klonen

1. IDE öffnen
2. Terminal öffnen (View → Terminal)
3. cd /home/coder/project
4. git clone <repo-url>
5. cd <project-name>
6. pio run -e d1_mini  # Test Build

Debugging

1. In src/main.cpp Breakpoint setzen
2. Run → Start Debugging (F5)
3. Verbindung zum Board muss vorhanden sein (Hardware-Debugger)
4. Breakpoints sollten pausieren

---

Integration mit Spawner

Automatischer Container-Spawn

Wenn ein Benutzer das vcoder-Template wählt:

1. Spawner erstellt Container mit user-template-vcoder:latest
2. Mountet Volumes für Workspace + PlatformIO Cache
3. Traefik routet Request zu Container unter https://coder.domain.com/{user-slug}-vcoder
4. Benutzer sieht code-server IDE
5. Workspace + Cache bleiben erhalten nach Neustart!

Admin-Dashboard Integration

Im Admin-Dashboard können Admins:

• ✅ Container starten/stoppen
• ✅ Container löschen (auch Workspace!)
• ✅ Logs ansehen
• ✅ Container-Status prüfen

---

Wartung & Updates

Backup des Workspaces

# Einzelnen User-Backup
tar -czf backup-vcoder-user-123.tar.gz /data/users/123/vcoder/

# Alle vcoder Workspaces
tar -czf backup-all-vcoder.tar.gz /data/users/*/vcoder/

Cleanup (Cache leeren)

# Toolchains löschen (wird beim nächsten Build neu heruntergeladen)
docker exec <container-id> rm -rf /home/coder/.platformio/packages/

# Kompletter Cache-Reset
docker exec <container-id> pio system prune --force

Updates für PlatformIO

Das Template ist mit festen Versionen konfiguriert:

• cpptools: 1.29.0
• platformio-ide: 3.3.4

Zum Update von Versionen:

# In user-template-vcoder/Dockerfile ändern:
ARG CPDTOOLS_VER=1.30.0  # Neue Version
ARG PIO_VER=3.4.0        # Neue Version

# Dann rebuild:
bash install.sh
docker-compose up -d --build

---

Weitere Verbesserungen (Optional)

Mögliche Features für Zukunft

1. Project Templates - Vorlagen für verschiedene Board-Typen
2. Library Management UI - GUI für Abhängigkeiten
3. Serial Monitor Integration - Im IDE integriert
4. Remote Upload - Upload-Gateway für Remote-Hardware
5. Device Manager - Konfiguration von angebundenen Boards
6. Firmware Comparison - Diff-Tool für Firmware-Versionen
7. Dokumentation Browser - Offline Arduino/ESP8266 Docs

---

Datenschutz & DSGVO

• ✅ Workspace-Dateien werden lokal in Containern gespeichert
• ✅ Keine Daten an Dritte übertragen
• ✅ Benutzer hat vollständige Kontrolle
• ✅ Einfaches Löschen möglich (Container + Volumes löschen)
• ✅ Extensions werden lokal im Container gecacht (kein Telemetrie)

---

Support & Issues

Bei Problemen:

1. Logs prüfen: docker logs container-id
2. IDE Erreichbarkeit: Browser auf https://coder.domain.com/...
3. Workspace: docker exec container-id ls -la /home/coder/project
4. PlatformIO: docker exec container-id pio --version
5. Build Fehler: Terminal in IDE nutzen für detailliertes Output

---

Version & Changelog

Version: 1.0.0 (2026-03-19)

Features

• ✅ code-server Web IDE mit Syntax Highlighting
• ✅ PlatformIO IDE Extension für Embedded Development
• ✅ C/C++ IntelliSense (cpptools + clangd)
• ✅ Workspace Persistierung (Docker Volumes)
• ✅ PlatformIO Toolchain Caching
• ✅ socat Port-Tunneling für PIO Home
• ✅ Spawner JWT Integration (--auth=none)

---

Lizenz & Attribution

Template: Container Spawner / vcoder Integration Basiert auf: codercom/code-server + PlatformIO Autor: Rainer Wieland Lizenz: MIT oder ähnlich

---

Letzte Aktualisierung

• Datum: 2026-03-19
• Version: 1.0.0
• Status: Production Ready ✅