spawner/docs/install

Installation

Anleitung zur Installation und Aktualisierung des Container Spawner.

🚀 Quick Links

• 📋 Deployment Guide - Vollständige Step-by-Step Anleitung für Deployment
  • Phase 1: Vorbereitung (Daten bereinigen, Environment konfigurieren)
  • Phase 2: Services starten
  • Phase 3: Erste Registrierung
  • Phase 4: Testing
  • Troubleshooting, Monitoring, Security Checklist

Inhaltsverzeichnis

• Quick Links
• Voraussetzungen
• Neuinstallation
• Update/Upgrade
• Umgebungsvariablen
• Manuelle Installation
• Troubleshooting

---

Voraussetzungen

Hardware

Komponente	Minimum	Empfohlen
RAM	2 GB	4+ GB
Disk	20 GB	50+ GB
CPU	2 Cores	4+ Cores

Software

• Docker: Version 20.10+
• Docker Compose: Version 2.0+
• Git: Fuer Repository-Clone
• Traefik: Version 2.x oder 3.x (laufend)
• curl oder wget: Fuer Installationsskript

Netzwerk

• Port 5000: Spawner-Service (intern)
• Port 80/443: Traefik Entrypoints
• Docker-Netzwerk: Traefik-Netzwerk muss existieren (Standard: web)
• DNS: Wildcard-DNS fuer Subdomains oder manuelle Eintraege

---

Neuinstallation

Schnellstart (Ein-Befehl-Installation)

# In ein leeres Verzeichnis wechseln
mkdir spawner && cd spawner

# Installationsskript ausfuehren
curl -sSL https://gitea.iotxs.de/RainerWieland/spawner/raw/branch/main/install.sh | bash

Das Skript erkennt automatisch, dass keine .env existiert und:

1. Laedt .env.example herunter
2. Gibt Anweisungen zur Konfiguration

Konfiguration anpassen

# Vorlage kopieren
cp .env.example .env

# Werte anpassen
nano .env

Wichtig: Mindestens diese Werte anpassen:

# Secret-Key generieren
python3 -c "import secrets; print(secrets.token_hex(32))"

# In .env eintragen:
SECRET_KEY=<generierter-key>
BASE_DOMAIN=deine-domain.de
SPAWNER_SUBDOMAIN=coder
TRAEFIK_NETWORK=web  # Name deines Traefik-Netzwerks

Installation abschliessen

bash install.sh

Das Skript:

1. Klont das Repository
2. Erstellt Verzeichnisse und setzt Berechtigungen (data/, logs/, .env)
3. Prueft/erstellt Docker-Netzwerk
4. Baut alle Docker-Images
5. Startet die Container

---

Update/Upgrade

Automatisches Update

cd /pfad/zu/spawner
bash install.sh

Das Skript erkennt automatisch ein bestehendes Git-Repository und:

1. Holt neueste Aenderungen (git pull)
2. Prueft/aktualisiert Verzeichnisrechte
3. Baut Images neu
4. Startet Container neu

Manuelles Update

cd /pfad/zu/spawner

# Aenderungen holen
git fetch origin
git pull origin main

# Images neu bauen
docker-compose down
docker build --no-cache -t user-service-template:latest ./user-template/
docker-compose build

# Container starten
docker-compose up -d

Rollback

# Zu spezifischer Version zurueck
git checkout v0.1.0
docker-compose down
docker-compose build
docker-compose up -d

---

Umgebungsvariablen

Pflicht-Variablen

Variable	Beschreibung	Beispiel
SECRET_KEY	Flask Session Secret	python3 -c "import secrets; print(secrets.token_hex(32))"
BASE_DOMAIN	Haupt-Domain	example.com
SPAWNER_SUBDOMAIN	Subdomain fuer Spawner-UI	coder
TRAEFIK_NETWORK	Docker-Netzwerk fuer Traefik	web

Traefik-Variablen

Variable	Standard	Beschreibung
TRAEFIK_CERTRESOLVER	lets-encrypt	Name des Certificate Resolvers aus traefik.yml
TRAEFIK_ENTRYPOINT	websecure	HTTPS Entrypoint Name

Optionale Variablen

Variable	Standard	Beschreibung
USER_TEMPLATE_IMAGE	user-service-template:latest	Docker-Image fuer User-Container
DEFAULT_MEMORY_LIMIT	512m	RAM-Limit pro Container
DEFAULT_CPU_QUOTA	50000	CPU-Quota (50000 = 0.5 CPU)
SPAWNER_PORT	5000	Interner Port des Spawners
LOG_LEVEL	INFO	Log-Level (DEBUG, INFO, WARNING, ERROR)
JWT_ACCESS_TOKEN_EXPIRES	3600	JWT Token Gueltigkeitsdauer (Sekunden)
CONTAINER_IDLE_TIMEOUT	3600	Timeout in Sekunden (noch nicht implementiert)

Email/SMTP-Variablen (fuer Verifizierung)

Variable	Standard	Beschreibung
SMTP_HOST	localhost	SMTP-Server Hostname
SMTP_PORT	587	SMTP-Server Port
SMTP_USER	``	SMTP-Benutzername
SMTP_PASSWORD	``	SMTP-Passwort
SMTP_FROM	noreply@localhost	Absender-Email-Adresse
SMTP_USE_TLS	true	TLS verwenden (true/false)
FRONTEND_URL	http://localhost:3000	Frontend-URL fuer Email-Links

Hinweis: Die Email-Konfiguration wird fuer die Email-Verifizierung bei der Registrierung und fuer Passwort-Reset-Emails benoetigt.

User-Templates (Dynamisches System)

Das System unterstützt beliebig viele User-Templates durch ein dynamisches Konfigurationssystem:

Verfügbare Standard-Templates:

Image	Verzeichnis	Beschreibung
user-template-01:latest	user-template-01/	Nginx Basic - Einfacher Nginx-Server
user-template-02:latest	user-template-02/	Nginx Advanced - Nginx mit erweiterten Features
user-template-next:latest	user-template-next/	Next.js Production - React-App mit Shadcn/UI

Konfiguration:

Templates werden in .env als semikolon-getrennte Liste definiert:

USER_TEMPLATE_IMAGES=user-template-01:latest;user-template-02:latest;user-template-next:latest

Automatisches Bauen:

Das install.sh Script erkennt automatisch alle user-template-* Verzeichnisse und baut sie.

Neues Template hinzufügen:

1. Erstelle user-template-xyz/Dockerfile
2. Füge zu .env ein: USER_TEMPLATE_IMAGES=...;user-template-xyz:latest
3. Füge Metadaten zu templates.json ein
4. Führe bash install.sh aus

Siehe auch: CLAUDE.md - Dynamisches Template-System

Produktions-Variablen

Variable	Beschreibung
DATABASE_URL	PostgreSQL-Verbindung (statt SQLite)
JWT_SECRET_KEY	Separater JWT-Secret
CORS_ORIGINS	Erlaubte CORS-Origins
DOCKER_HOST	Docker Socket Pfad (Standard: unix:///var/run/docker.sock)

---

Manuelle Installation

Falls das Installationsskript nicht verwendet werden kann:

# 1. Repository klonen
git clone https://gitea.iotxs.de/RainerWieland/spawner.git
cd spawner

# 2. Konfiguration erstellen
cp .env.example .env
nano .env  # Werte anpassen

# 3. Verzeichnisse und Rechte setzen
mkdir -p data logs
chmod 755 data logs
chmod 600 .env

# 4. Docker-Netzwerk pruefen
docker network ls | grep web
# Falls nicht vorhanden:
docker network create web

# 5. User-Template Images bauen
docker build -t user-service-template:latest ./user-template/
docker build -t user-template-next:latest ./user-template-next/  # Optional

# 6. Spawner bauen und starten
docker-compose build
docker-compose up -d

# 7. Logs pruefen
docker-compose logs -f spawner

---

Troubleshooting

Spawner startet nicht

# Logs pruefen
docker-compose logs spawner

# Health-Check
curl http://localhost:5000/health

Haeufige Ursachen:

• .env fehlt oder hat falsche Werte
• Docker-Socket nicht gemountet
• Netzwerk existiert nicht

Container wird nicht erstellt

# Docker-Verbindung testen
docker ps

# Template-Image pruefen
docker images | grep user-service-template

Haeufige Ursachen:

• Template-Image nicht gebaut
• Netzwerk-Name falsch in .env

Traefik routet nicht

# Traefik-Dashboard pruefen (falls aktiviert)
# Container-Labels pruefen
docker inspect spawner | jq '.[0].Config.Labels'

# Netzwerk-Verbindung pruefen
docker network inspect web | grep spawner

Haeufige Ursachen:

• Container nicht im Traefik-Netzwerk
• Labels falsch konfiguriert
• DNS nicht konfiguriert

Datenbank-Fehler

# In Container einsteigen
docker exec -it spawner bash

# DB manuell initialisieren
python -c "from app import app, db; app.app_context().push(); db.create_all()"

---

Verzeichnisrechte

Das Installationsskript setzt die Berechtigungen automatisch. Bei manueller Installation muessen diese selbst gesetzt werden.

Vom Skript automatisch gesetzt

Pfad	Berechtigung	Zweck
./data/	755	SQLite-Datenbank
./logs/	755	Log-Dateien
./.env	600	Sensible Konfiguration (nur Owner)
./install.sh	+x	Ausfuehrbar

Vom System benoetigt

Pfad	Berechtigung	Zweck
/var/run/docker.sock	rw	Docker-API-Zugriff

Manuelle Rechte setzen

# Verzeichnisse erstellen
mkdir -p data logs

# Berechtigungen setzen
chmod 755 data logs
chmod 600 .env
chmod +x install.sh

Non-Root Container

Falls der Spawner-Container als non-root User laeuft, muessen die Verzeichnisse fuer diesen beschreibbar sein:

# Option 1: Volle Schreibrechte (einfach, aber weniger sicher)
chmod 777 data logs

# Option 2: Owner auf Container-UID setzen (empfohlen)
# UID des Container-Users ermitteln und setzen
chown 1000:1000 data logs

Synology NAS Hinweis

Auf Synology NAS (DSM) kann es noetig sein, die Verzeichnisse dem Docker-User zuzuweisen:

# Als root auf der Synology
chown -R 1000:1000 /volume1/docker/spawner/data
chown -R 1000:1000 /volume1/docker/spawner/logs

---

Synology NAS / BusyBox Kompatibilitaet

Das Installationsskript ist vollstaendig kompatibel mit Synology NAS und anderen BusyBox-basierten Systemen.

Automatische Anpassungen

Das Skript erkennt und behandelt automatisch:

Problem	Loesung
git safe.directory Fehler	Automatische Konfiguration
Kein sort -V (Versionsort)	Eigene Versionsvergleich-Funktion
Kein grep -P (Perl-Regex)	POSIX-kompatible Alternativen
Kein --progress=plain	Flag wird nicht verwendet
Aeltere Docker-Version	BuildKit-Features deaktiviert

Bekannte Einschraenkungen auf Synology

1. Build-Zeit: Docker-Builds dauern laenger (5-15 Min fuer Next.js)
2. RAM: Mindestens 4 GB RAM empfohlen
3. Docker-Version: Synology verwendet oft aeltere Docker-Versionen

Manuelle Vorbereitung (optional)

# Als root auf der Synology einloggen
sudo -i

# In Installationsverzeichnis wechseln
cd /volume1/docker
mkdir spawner
cd spawner

# Installation starten
curl -sSL https://gitea.iotxs.de/RainerWieland/spawner/raw/branch/main/install.sh | bash

Troubleshooting Synology

"dubious ownership" Fehler

Falls dieser Fehler auftritt:

git config --global --add safe.directory /volume1/docker/spawner

Das Skript macht dies automatisch, aber bei Problemen kann es manuell ausgefuehrt werden.

Docker-Build schlaegt fehl

# Build-Logs pruefen
cat /tmp/build-user-template.log
cat /tmp/build-spawner.log
cat /tmp/build-frontend.log

# Images manuell bauen
cd /volume1/docker/spawner
docker build -t user-service-template:latest ./user-template/
docker build -t spawner:latest .
docker build -t spawner-frontend:latest ./frontend/

Container startet nicht

# Logs pruefen
docker logs spawner
docker logs spawner-frontend

# Netzwerk pruefen
docker network ls
docker network inspect web

---

Zurueck zur Dokumentations-Uebersicht