spawner/docs/VCODER_PITCH.md

💻 vcoder: Cloud IDE für Maker & Embedded Developers

🎯 Vision

Stell dir vor: Jeder Maker bekommt seine eigene Cloud-IDE für ESP8266-Entwicklung – persistenter Workspace, PlatformIO vorinstalliert, direkt im Browser, geschützt durch JWT.

Keine lokale Installation. Keine Komplikationen. Einfach Login und coden.

---

🏗️ Architektur: Das Spawner Ökosystem

Was ist Container Spawner?

Ein Production-Stack für persönliche Developer-Umgebungen:

┌─────────────────────────────────────────────────────────┐
│                    Browser / Nutzer                      │
└────────────────────┬──────────────────────────────────────┘
                     │
                     ▼
         ┌──────────────────────┐
         │   Traefik Reverse    │
         │      Proxy (SSL)     │
         └──────────┬───────────┘
                    │
         ┌──────────┼──────────┐
         ▼          ▼          ▼
    ┌────────┐ ┌────────┐ ┌────────┐
    │ user1  │ │ user2  │ │ user3  │
    │ IDE    │ │ Docs   │ │ Chat   │  ← Isolierte Container
    │ vcoder │ │ Wiki   │ │ API    │     pro User
    └────────┘ └────────┘ └────────┘
         │          │          │
         └──────────┼──────────┘
                    ▼
      ┌─────────────────────────┐
      │  Docker Volumes (Daten) │
      │  /data/users/{id}/      │
      └─────────────────────────┘

Kernfeatures:

• ✅ Passwordless Auth: Magic Links per Email (keine Passwörter!)
• ✅ Multi-Template System: Templates sind einfach Docker Images
• ✅ Persistent Data: User-Daten bleiben über Container-Restarts erhalten
• ✅ JWT Security: HttpOnly Cookies, CSRF-Schutz
• ✅ Skalierbar: Jeden User in eigenem Container isolieren

Die Template-Architektur

Ein Template = ein Docker Image mit einer speziellen Applikation:

Template	Beschreibung	Status
template-01	Nginx Basic	✅ Stable
template-next	Next.js React App	✅ Stable
dictionary	Persönliches Wörterbuch (Flask)	✅ Working
vcoder	ESP8266 IDE (code-server + PlatformIO)	🟡 Beta

Jeder User wählt sein Template im Dashboard → Spawner startet automatisch einen isolierten Container → User erhält eigene URL: https://spawner.domain.com/<slug>-<template>

---

🚀 Was ist vcoder?

Features

code-server (VS Code im Browser):

• 💬 Full IntelliSense & Code-Completion
• 🎨 Syntax Highlighting für alle Sprachen
• 📦 Extension-Marketplace (OpenVSX)
• 🔌 Terminal integriert
• 💾 File Explorer & Git Integration
• 🌙 Dark Mode

PlatformIO (Embedded Development IDE):

• 🎯 One-Click Project Creation (wähle Board → Template generiert)
• 🔨 Build & Compile für ESP8266, Wemos, Arduino, STM32, etc.
• ⬆️ Upload-Tool (USB via Host, oder Remote-API)
• 📊 Serial Monitor für Debugging
• 📚 Intellisense für 100+ Boards/Plattformen
• 🛠️ Package Manager (automatisches Herunterladen von Toolchains)

Persistenz:

• 💾 Workspace Volume: /home/coder/project/ bleibt nach Restart erhalten
• 📦 Toolchain Cache: /home/coder/.platformio/ (200MB) wird nicht jedes Mal neu heruntergeladen

Security:

• 🔐 Spawner JWT-Cookie: Automatische Authentifizierung (kein separates Login für IDE)
• 🛡️ Unprivileged User: code-server läuft als coder, nicht root
• 🚫 Isolated Container: Kein Zugriff auf Docker Socket oder Host

---

✅ Was ist bereits fertig?

• ✅ Dockerfile basiert auf codercom/code-server:latest + PlatformIO

  • cpptools (Microsoft C/C++) heruntergeladen & installiert
  • platformio-ide Extension installiert
  • clangd für Language-Server Protocol

• ✅ Spawner Integration

  • Template in templates.json registriert
  • Volumes für Workspace + PlatformIO Cache konfiguriert
  • Container-Spawn mit JWT automatisiert
  • Dashboard zeigt "💻 ESP8266 IDE" Template

• ✅ Traefik Routing

  • https://spawner.domain.com/<slug>-vcoder → Container automatisch geroutet
  • StripPrefix Middleware entfernt /<slug>-vcoder bevor Request zum Container

• ✅ Dokumentation

  • Vollständiges Setup & Deployment Guide
  • REST API Specs wenn nötig
  • Troubleshooting-Kapitel

---

🔴 Offene Baustellen (Die Challenges)

1. Subpath-Problem: Code-Server Asset Loading (KRITISCH)

Problem:

GET /e220dd278a12-template-vcoder (200 OK - HTML)
  ├─ GET /stable-a6d80dc434b8774c92d0c7b548a24a35b8ac4a45/static/out/workbench.css (404 NOT FOUND) ❌
  ├─ GET /stable-a6d80dc434b8774c92d0c7b548a24a35b8ac4a45/static/out/nls.messages.js (404 NOT FOUND) ❌
  └─ GET /manifest.json (404 NOT FOUND) ❌

Root Cause:

• Traefik StripPrefix entfernt /<slug>-vcoder aus dem Request Path
• code-server erwartet aber, dass Assets unter /<prefix>/ liegen (relative URLs)
• Stattdessen lädt code-server /stable.../static/... von der Root

Lösungsansätze:

1. nginx Reverse Proxy im Container (current attempt):

   • nginx auf Port 8080 (public)
   • code-server auf Port 8081 (internal)
   • nginx proxy-passiert alles zu code-server
   • Problem: Permission-Fehler (unprivileged user kann /var/log/nginx/ nicht schreiben)

2. code-server Configuration (ideal):

   • code-server hat --base-path Flag? (Nein, unterstützt nicht in v4.111.0)
   • Custom Proxy-Headers in Traefik? (Komplex)

3. Traefik Middleware (hacky):

   • RewritePathRegex Middleware URLs umschreiben?
   • Plugin für Path-Injection?

Status: 🔴 BLOCKIERT - Subpath-Routing funktioniert nicht

---

2. nginx Permissions: Unprivileged User (TECHNIK)

Problem:

[emerg] 8#8: "daemon" directive is duplicate in /etc/nginx/nginx.conf:1
[emerg] 8#8: open() "/var/log/nginx/error.log" failed (13: Permission denied)

Root Cause:

• code-server läuft als coder User (unprivileged, sicherer)
• nginx Default-Config braucht root-Privilegien oder /var/log/nginx/ Schreibrecht
• /var/log/nginx/ hat Permissions 755 (nur root kann schreiben)

Lösungsansätze:

1. Logs nach /tmp umleiten:

   error_log /tmp/nginx-error.log;
   access_log /tmp/nginx-access.log;
   daemon off;  # Nicht doppelt definieren!
   

2. Minimal nginx Config schreiben (kein root-User-Direktive)

3. Alpine Linux nutzen (kleineres Footprint)

4. supervisord statt nginx (optional, weniger Dependencies)

Status: 🟡 IN PROGRESS - Technical fix nötig

---

3. JWT-Cookie Authentifizierung (SICHERHEIT)

Problem:

• Dictionary-Template validiert JWT im before_request Hook
• vcoder braucht gleiches Verhalten (falls API-Endpoints hinzukommen)
• Aktuell: Cookie wird nicht automatisch vom Container validiert

Lösungsansatz:

• code-server exponiert keine API (ist pure WebUI)
• WebSocket-Connection (wss://) braucht evtl. Cookie-Validierung auf Proxy-Ebene
• Traefik-Middleware kann Cookie prüfen, bevor Request zum Container kommt

Status: 🟡 OPTIONAL - Nur wichtig wenn APIs später hinzukommen

---

4. PlatformIO Home Proxy (UNTESTED)

Problem:

• PlatformIO startet intern einen "Home" Server auf Port 9009
• Sollte über nginx zu Port 8008 tunnelt werden (socat)
• Noch nicht getestet ob das funktioniert

Lösungsansatz:

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

Status: 🟡 UNGETESTET - Braucht Test auf echtem System

---

📋 Konkrete Aufgaben für Entwickler

Task 1: Fix nginx Permissions (⏱️ ~2h, 🟡 Mittel)

Was tun:

1. user-template-vcoder/Dockerfile updaten
2. nginx Config schreiben ohne daemon Duplizierung
3. Logs zu /tmp umleiten
4. Build testen: docker build -t user-template-vcoder:latest ./user-template-vcoder/
5. Logs prüfen: docker logs <container> sollte kein emerg Error mehr zeigen

Dateien:

• user-template-vcoder/Dockerfile (Zeilen 62-77)

Acceptance Criteria:

• ✅ nginx startet ohne Permission-Fehler
• ✅ docker logs <container> zeigt "code-server listening on http://127.0.0.1:8081"

---

Task 2: Löse code-server Asset-Loading Problem (⏱️ ~4h, 🔴 Schwer)

Was tun:

1. Verstehe warum code-server Assets von /stable.../ lädt (schaue HTML)
2. Prüfe ob nginx Reverse Proxy jetzt funktioniert (nach Task 1)
3. Falls nicht: Implementiere alternative Lösung (z.B. Traefik Middleware)
4. Test im Browser: https://spawner.domain.com/<slug>-vcoder/ sollte vollständig geladen sein

Dateien:

• user-template-vcoder/Dockerfile (nginx Config)
• Optional: container_manager.py (Traefik Labels)

Acceptance Criteria:

• ✅ IDE lädt komplett (keine 404-Fehler in Network-Tab)
• ✅ CSS & JavaScript ist vorhanden (IDE sieht nicht weiß aus)
• ✅ Code-Completion funktioniert

---

Task 3: JWT-Cookie & Dictionary-Style Auth (⏱️ ~2h, 🟡 Leicht)

Was tun:

1. Schaue wie user-template-dictionary/app.py JWT validiert
2. Implementiere ähnliche Validierung im vcoder Container (falls API nötig wird)
3. Teste mit curl: curl -b "spawner_token=..." https://spawner.domain.com/<slug>-vcoder/api/...

Dateien:

• user-template-dictionary/app.py (Zeilen 63-103, JWT-Validierung)

Acceptance Criteria:

• ✅ Ohne gültigen Token: 401 Unauthorized
• ✅ Mit gültigem Token: API-Zugriff funktioniert

---

Task 4: PlatformIO Home Proxy testen (⏱️ ~1h, 🟡 Leicht)

Was tun:

1. IDE starten (Task 2 muss funktionieren)
2. PlatformIO IDE Extension öffnen
3. PlatformIO Home sollte auf Port 8008 erreichbar sein (über socat Tunnel)
4. Test: Neue PlatformIO Project erstellen über UI

Dateien:

• user-template-vcoder/Dockerfile (Zeilen 80-83, Entrypoint)

Acceptance Criteria:

• ✅ PlatformIO Home lädt ohne Fehler
• ✅ "Create Project" Button funktioniert
• ✅ Board-Auswahl lädt korrekt

---

Task 5: ESP8266 Test-Projekt Dokumentieren (⏱️ ~1h, 🟡 Leicht)

Was tun:

1. IDE starten & neues PlatformIO Projekt für "Wemos D1 Mini" erstellen
2. Hello-World Firmware schreiben (Serial Output)
3. Dokumentation schreiben: docs/examples/VCODER_HELLOWORLD.md
4. Schritt-für-Schritt Guide (Setup → Build → Upload)

Dateien:

• docs/examples/VCODER_HELLOWORLD.md (neu)

Acceptance Criteria:

• ✅ Guide ist reproduzierbar von zero
• ✅ Code-Beispiel enthalten
• ✅ Troubleshooting Section

---

🛠️ Tech Stack & Einstieg

Tech Stack

Frontend Layer:       Traefik (Reverse Proxy, SSL)
                      ↓
Web Server:           nginx (in vcoder Container)
                      ↓
App Server:           code-server (VS Code)
                      ↓
IDE Extensions:       PlatformIO IDE, cpptools, clangd
                      ↓
Toolchain:            PlatformIO (ESP8266 SDK, esptool, etc.)
                      ↓
Persistenz:           Docker Volumes (/data/users/{id}/vcoder)

Orchestration:        Docker + docker-compose
CI/CD:                GitHub/Gitea + git
Lang:                 Python (Spawner), JavaScript (code-server), C++ (Firmware)

Schnelleinstieg

1. Repo klonen:

git clone https://gitea.iotxs.de/RainerWieland/spawner.git
cd spawner

2. Lokal bauen & testen:

docker build -t user-template-vcoder:latest ./user-template-vcoder/
docker run --rm -p 8080:8080 user-template-vcoder:latest &
curl http://localhost:8080/  # Sollte HTML zurückgeben

3. Wichtigste Dateien:

• user-template-vcoder/Dockerfile - Container Definition
• container_manager.py - Spawner Integration (Volumes, Traefik Labels)
• docs/templates/VCODER_TEMPLATE.md - Vollständige Doku

4. Slack/Discord Channel:

• Link zum Team-Chat (falls vorhanden)
• Fragen? → Hier anschreiben!

---

💡 Warum mitmachen?

Für dein Portfolio

• 🚀 Production Stack: Nicht nur Tutorial-Code, sondern echte Nutzer auf Synology NAS
• 📚 Modern Tech: Docker, Traefik, code-server, PlatformIO, JWT, Next.js
• 🎓 Full-Stack: Backend (Python), Frontend (React), Infrastructure (Docker)
• 🌍 Open Source Feel: Clean Code, Git-based Workflow, Dokumentation

Für die Community

• 👥 Maker-Community profitiert direkt von der IDE
• 🎉 Educational Value: Perfect für Workshops & Teaching
• 🚀 Low Barrier to Entry: Keine lokale Installation, nur Browser
• 💾 Persistent Data: Deine Projekte bleiben dir erhalten

Für die Technologie

• 🔧 Container Orchestration: Hands-on mit Docker & Traefik
• 🔐 Security: JWT, CORS, Unprivileged Users, Isolation
• ⚡ Performance: WebSocket Proxying, Asset Caching, Subpath Routing
• 📊 Scalability: Spawn unbegrenzt viele User-Container

---

📞 Kontakt & Support

Repo: https://gitea.iotxs.de/RainerWieland/spawner

Doku:

• Installation: docs/install/DEPLOYMENT_GUIDE.md
• vcoder Spezifisch: docs/templates/VCODER_TEMPLATE.md
• Architektur: docs/architecture/ (falls vorhanden)

Issues & PRs:

• Nutze GitHub Issues für Bugs
• PRs für neue Features (bitte vorher absprechen!)
• Commit-Messages: Deutsch oder Englisch (egal, aber consistent)

Fragen?

• Kontaktiere: @RainerWieland (GitHub/Gitea)
• Oder: Schreib eine Issue mit Label question

---

🎯 Nächste Schritte

1. Schnelleinstieg: Task 1 beginnen (nginx Permissions)
2. Dann: Task 2 (Asset Loading) - das ist die Hauptchallenge
3. Testing: Task 4 (PlatformIO Home)
4. Dokumentation: Task 5 (Hello World)

Timeline: 2-3 Tage für alles (mit regulärem Job machbar)

Viel Spaß! 🚀

---

Version & Changelog

Pitch Version: 1.0.0 (2026-03-19) vcoder Template Version: 0.1.0-beta Status: 🟡 Beta - Bereit für Community Contributions

---

Made with ❤️ for Makers & Embedded Developers