From cfce1064732d1d43d67ddcaa3c74928a860283bb Mon Sep 17 00:00:00 2001
From: "XPS\\Micro" <Rainer Wieland>
Date: Wed, 25 Mar 2026 06:25:59 +0100
Subject: [PATCH] docs: Add vcoder Developer Pitch Document

Comprehensive pitch document to attract developers for vcoder integration.

Content includes:
- Vision & architecture overview
- What's already working (Dockerfile, Spawner integration, Traefik routing)
- Open technical challenges (Subpath routing, nginx permissions, auth)
- 5 concrete tasks with time estimates & acceptance criteria
- Tech stack overview & quick-start guide
- Community & portfolio value proposition

Target audience: Developers interested in Docker, embedded systems, and infrastructure

This document serves as the main entry point for new contributors.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
---
 docs/VCODER_PITCH.md | 419 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 419 insertions(+)
 create mode 100644 docs/VCODER_PITCH.md

diff --git a/docs/VCODER_PITCH.md b/docs/VCODER_PITCH.md
new file mode 100644
index 0000000..4a77043
--- /dev/null
+++ b/docs/VCODER_PITCH.md
@@ -0,0 +1,419 @@
+# 💻 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:**
+```bash
+[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:**
+   ```nginx
+   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:**
+```bash
+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:**
+```bash
+git clone https://gitea.iotxs.de/RainerWieland/spawner.git
+cd spawner
+```
+
+**2. Lokal bauen & testen:**
+```bash
+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**