History

$XPS\Micro$ XPS\Micro c363351483 Initial project structure with documentation		2026-01-30 18:00:41 +01:00
..
README.md	Initial project structure with documentation	2026-01-30 18:00:41 +01:00

README.md

Best Practices - Dos and Don'ts

Empfehlungen fuer den sicheren und effizienten Betrieb des Container Spawners.

Inhaltsverzeichnis

Produktions-Checkliste
Dos - Empfohlene Praktiken
Don'ts - Zu vermeiden
Haeufige Fehler

Produktions-Checkliste

Vor dem Go-Live

Kategorie	Aufgabe	Status
Sicherheit	SECRET_KEY generiert (min. 32 Bytes)	[ ]
	`.env` nicht im Repository	[ ]
	HTTPS aktiviert	[ ]
	Docker Socket Proxy konfiguriert	[ ]
Konfiguration	BASE_DOMAIN korrekt	[ ]
	TRAEFIK_NETWORK existiert	[ ]
	Resource-Limits angemessen	[ ]
Infrastruktur	DNS-Eintraege (Wildcard)	[ ]
	Traefik laeuft stabil	[ ]
	Firewall konfiguriert	[ ]
Monitoring	Health-Check funktioniert	[ ]
	Logs werden geschrieben	[ ]
	Backup-Strategie	[ ]
Testing	Login/Signup funktioniert	[ ]
	Container wird erstellt	[ ]
	Subdomain erreichbar	[ ]

Dos - Empfohlene Praktiken

Konfiguration

DO: SECRET_KEY sicher generieren

# Guter Key (32 Bytes = 64 Hex-Zeichen)
python3 -c "import secrets; print(secrets.token_hex(32))"

DO: Umgebungsvariablen fuer sensible Daten

# In .env (nie committen!)
SECRET_KEY=abc123...
DATABASE_URL=postgresql://...

DO: Resource-Limits setzen

# In .env
DEFAULT_MEMORY_LIMIT=512m
DEFAULT_CPU_QUOTA=50000

Deployment

DO: Docker Compose fuer Orchestrierung

# Nicht einzelne docker run Befehle
docker-compose up -d
docker-compose logs -f
docker-compose down

DO: Images taggen

# Versionierte Tags statt :latest in Produktion
docker build -t spawner:0.1.0 .
docker build -t spawner:latest .

DO: Health-Checks nutzen

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:5000/health"]
  interval: 30s
  timeout: 10s
  retries: 3

Monitoring

DO: Logs zentralisieren

# docker-compose.yml
logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"

DO: Regelmaessige Backups

# Cronjob fuer taegliches Backup
0 2 * * * /pfad/zu/spawner/backup.sh

DO: Disk-Space ueberwachen

# Docker-Ressourcen pruefen
docker system df
docker system prune -f  # Vorsicht in Produktion!

Sicherheit

DO: HTTPS erzwingen

# Traefik-Labels
- "traefik.http.routers.spawner.entrypoints=websecure"
- "traefik.http.routers.spawner.tls=true"

DO: Minimale Berechtigungen

# Docker Socket Proxy statt direktem Zugriff
DOCKER_HOST: tcp://docker-proxy:2375

DO: Container als Non-Root

# Im User-Template
USER nginx
# oder
RUN useradd -m appuser && chown -R appuser /app
USER appuser

Don'ts - Zu vermeiden

Konfiguration

DON'T: Hardcoded Secrets

# NIEMALS!
SECRET_KEY = "supersecret123"

DON'T: Debug-Mode in Produktion

# NIEMALS in Produktion!
app.run(debug=True)
FLASK_DEBUG=1

DON'T: Schwache Keys

# ZU KURZ / ZU EINFACH
SECRET_KEY=test
SECRET_KEY=12345

Deployment

DON'T: Manuelles Container-Management

# Vermeiden - besser docker-compose
docker run -d --name spawner ...
docker stop spawner
docker rm spawner

DON'T: Unversionierte Images in Produktion

# Vermeiden
USER_TEMPLATE_IMAGE=user-service-template:latest

# Besser
USER_TEMPLATE_IMAGE=user-service-template:0.1.0

DON'T: Ohne Health-Checks deployen

Sicherheit

DON'T: Docker Socket direkt exponieren

# NIEMALS!
ports:
  - "2375:2375"  # Docker API oeffentlich

DON'T: .env committen

# .gitignore MUSS enthalten:
.env
*.db

DON'T: Container ohne Resource-Limits

# Vermeiden - DoS-Risiko
container = client.containers.run(image)

# Besser
container = client.containers.run(
    image,
    mem_limit='512m',
    cpu_quota=50000
)

DON'T: Root-Container in Produktion

Wartung

DON'T: Logs ignorieren

# Regelmaessig pruefen!
docker-compose logs --tail=100 spawner

DON'T: Backups vergessen

DON'T: Updates aufschieben

# Regelmaessig aktualisieren
git pull origin main
docker-compose build
docker-compose up -d

Haeufige Fehler

1. "Connection refused" beim Health-Check

Ursache: Container noch nicht bereit

Loesung: Warten oder start_period erhoehen:

healthcheck:
  start_period: 30s

2. "Network not found"

Ursache: Traefik-Netzwerk existiert nicht

Loesung:

docker network create web
# Oder TRAEFIK_NETWORK in .env anpassen

3. "Permission denied" bei Docker Socket

Ursache: Spawner-Container hat keinen Zugriff

Loesung:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock:rw

Oder Docker-Gruppe:

sudo usermod -aG docker $USER

4. "Image not found"

Ursache: User-Template nicht gebaut

Loesung:

docker build -t user-service-template:latest ./user-template/

5. Subdomain nicht erreichbar

Ursache: DNS oder Traefik-Konfiguration

Diagnose:

# DNS pruefen
nslookup username.example.com

# Traefik-Routes pruefen (Dashboard)
# Container-Labels pruefen
docker inspect user-xxx | jq '.[0].Config.Labels'

6. "Database locked"

Ursache: SQLite-Konkurrenzzugriff

Loesung fuer Produktion: PostgreSQL verwenden:

DATABASE_URL=postgresql://spawner:pass@postgres:5432/spawner

7. Container startet, aber Service nicht erreichbar

Ursache: Falscher Port in Labels

Loesung: Port in container_manager.py pruefen:

# Muss mit EXPOSE im Dockerfile uebereinstimmen
f'traefik.http.services.user{user_id}.loadbalancer.server.port': '8080'

Quick Reference

Nuetzliche Befehle

# Status
docker-compose ps
docker ps --filter 'label=spawner.managed=true'

# Logs
docker-compose logs -f spawner
docker logs user-xxx-1

# Neustart
docker-compose restart spawner

# Komplett neu
docker-compose down
docker-compose up -d --build

# Cleanup
docker system prune -f
docker volume prune -f

Debugging

# In Container einsteigen
docker exec -it spawner bash

# Python-Shell
docker exec -it spawner python

# Datenbank
docker exec spawner sqlite3 /app/data/users.db ".tables"

Zurueck zur Dokumentations-Uebersicht