cfce106473
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>
420 lines
14 KiB
Markdown
420 lines
14 KiB
Markdown
# 💻 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**
|