RainerWieland/spawner

Fork 0

$XPS\Micro$ XPS\Micro b6fd832311 Update documentation: CHANGELOG v0.2.0, Synology compatibility guide

2026-01-31 00:01:32 +01:00

9.8 KiB

Raw Blame History

Installation

Anleitung zur Installation und Aktualisierung des Container Spawner.

Inhaltsverzeichnis

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:

Laedt .env.example herunter
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:

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

Update/Upgrade

Automatisches Update

cd /pfad/zu/spawner
bash install.sh

Das Skript erkennt automatisch ein bestehendes Git-Repository und:

Holt neueste Aenderungen (git pull)
Prueft/aktualisiert Verzeichnisrechte
Baut Images neu
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)

User-Templates

Es stehen zwei Templates fuer User-Container zur Verfuegung:

Image	Verzeichnis	Beschreibung
`user-service-template:latest`	`user-template/`	Einfache nginx-Willkommensseite (Standard)
`user-template-next:latest`	`user-template-next/`	Moderne Next.js React-Anwendung

Um ein anderes Template zu verwenden, aendere USER_TEMPLATE_IMAGE in .env:

USER_TEMPLATE_IMAGE=user-template-next:latest

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

Build-Zeit: Docker-Builds dauern laenger (5-15 Min fuer Next.js)
RAM: Mindestens 4 GB RAM empfohlen
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

9.8 KiB Raw Blame History

Installation

Inhaltsverzeichnis

Voraussetzungen

Hardware

Software

Netzwerk

Neuinstallation

Schnellstart (Ein-Befehl-Installation)

Konfiguration anpassen

Installation abschliessen

Update/Upgrade

Automatisches Update

Manuelles Update

Rollback

Umgebungsvariablen

Pflicht-Variablen

Traefik-Variablen

Optionale Variablen

User-Templates

Produktions-Variablen

Manuelle Installation

Troubleshooting

Spawner startet nicht

Container wird nicht erstellt

Traefik routet nicht

Datenbank-Fehler

Verzeichnisrechte

Vom Skript automatisch gesetzt

Vom System benoetigt

Manuelle Rechte setzen

Non-Root Container

Synology NAS Hinweis

Synology NAS / BusyBox Kompatibilitaet

Automatische Anpassungen

Bekannte Einschraenkungen auf Synology

Manuelle Vorbereitung (optional)

Troubleshooting Synology

"dubious ownership" Fehler

Docker-Build schlaegt fehl

Container startet nicht

9.8 KiB

Raw Blame History