From 80bf8bc58d3906170936e0388927f6c33b8d2c29 Mon Sep 17 00:00:00 2001 From: olaf Date: Mon, 6 Oct 2025 19:26:13 +0000 Subject: [PATCH] Add deploymnent guides for Debian and Ubuntu --- deployment-debian.md | 336 ++++++++++++++++++++++++++++++++++ deployment-ubuntu.md | 417 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 753 insertions(+) create mode 100644 deployment-debian.md create mode 100644 deployment-ubuntu.md diff --git a/deployment-debian.md b/deployment-debian.md new file mode 100644 index 0000000..feefe8d --- /dev/null +++ b/deployment-debian.md @@ -0,0 +1,336 @@ +# Infoscreen Deployment Guide (Debian) + +Komplette Anleitung für das Deployment des Infoscreen-Systems auf einem Debian-Server (Bookworm/Trixie) mit GitHub Container Registry. + +## 📋 Übersicht + +- **Phase 0**: Docker Installation (optional) +- **Phase 1**: Images bauen und zur Registry pushen +- **Phase 2**: Debian-Server Vorbereitung +- **Phase 3**: System-Konfiguration und Start + +--- + +## 🐳 Phase 0: Docker Installation (optional) + +Falls Docker noch nicht installiert ist, wählen Sie eine der folgenden Optionen: + +### Option A: Debian Repository (schnell, aber oft ältere Version) + +```bash +sudo apt update +sudo apt install -y docker.io docker-compose-plugin +sudo systemctl enable docker +sudo systemctl start docker +``` + +### Option B: Offizielle Docker-Installation (empfohlen für Produktion) + +```bash +# Alte Docker-Versionen entfernen (falls vorhanden) +sudo apt remove -y docker docker-engine docker.io containerd runc + +# Abhängigkeiten installieren +sudo apt update +sudo apt install -y ca-certificates curl gnupg lsb-release + +# Repository-Schlüssel hinzufügen +sudo install -m 0755 -d /etc/apt/keyrings +curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg +sudo chmod a+r /etc/apt/keyrings/docker.gpg + +# Debian Codename ermitteln (bookworm / trixie / bullseye ...) +source /etc/os-release +echo "Using Debian release: $VERSION_CODENAME" + +# Docker Repository hinzufügen +echo \ + "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \ + $VERSION_CODENAME stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null + +# Docker installieren (neueste aus dem offiziellen Repo) +sudo apt update +sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin + +# Docker aktivieren +sudo systemctl enable docker +sudo systemctl start docker + +# Benutzer zur docker-Gruppe hinzufügen (für Root-losen Zugriff) +sudo usermod -aG docker $USER + +echo "Bitte neu einloggen (SSH Sitzung beenden und neu verbinden), damit die Gruppenzugehörigkeit aktiv wird." +``` + +### Docker-Installation testen + +```bash +docker run hello-world +docker --version +docker compose version +``` + +--- + +## 🏗️ Phase 1: Images bauen und pushen (lokale Entwicklungsmaschine) + +### 1. GitHub Container Registry Login + +```bash +# Personal Access Token (write:packages) verwenden +echo $GITHUB_TOKEN | docker login ghcr.io -u robbstarkaustria --password-stdin + +# Alternativ interaktiv +docker login ghcr.io +# Username: robbstarkaustria +# Password: [GITHUB_TOKEN] +``` + +### 2. Images bauen und taggen + +```bash +cd /workspace + +docker build -f server/Dockerfile -t ghcr.io/robbstarkaustria/infoscreen-api:latest . +docker build -f dashboard/Dockerfile -t ghcr.io/robbstarkaustria/infoscreen-dashboard:latest . +docker build -f listener/Dockerfile -t ghcr.io/robbstarkaustria/infoscreen-listener:latest . +docker build -f scheduler/Dockerfile -t ghcr.io/robbstarkaustria/infoscreen-scheduler:latest . +``` + +### 3. Images pushen + +```bash +docker push ghcr.io/robbstarkaustria/infoscreen-api:latest +docker push ghcr.io/robbstarkaustria/infoscreen-dashboard:latest +docker push ghcr.io/robbstarkaustria/infoscreen-listener:latest +docker push ghcr.io/robbstarkaustria/infoscreen-scheduler:latest + +docker images | grep ghcr.io +``` + +--- + +## 🖥️ Phase 2: Debian-Server Vorbereitung + +### 4. Grundsystem aktualisieren + +```bash +sudo apt update && sudo apt upgrade -y +sudo apt install -y git curl wget + +# Falls Docker noch fehlt → Phase 0 ausführen +``` + +### 5. Deployment-Dateien übertragen + +```bash +mkdir -p ~/infoscreen-deployment +cd ~/infoscreen-deployment + +scp user@dev-machine:/workspace/docker-compose.prod.yml . +scp user@dev-machine:/workspace/.env . +scp user@dev-machine:/workspace/nginx.conf . +scp -r user@dev-machine:/workspace/certs ./ +scp -r user@dev-machine:/workspace/mosquitto ./ + +# Alternative Paketierung: +# (auf Entwicklungsrechner) +# tar -czf infoscreen-deployment.tar.gz docker-compose.prod.yml .env nginx.conf certs/ mosquitto/ +# scp infoscreen-deployment.tar.gz user@server:~/ +# (auf Server) +# tar -xzf infoscreen-deployment.tar.gz -C ~/infoscreen-deployment +``` + +### 6. Mosquitto-Konfiguration (falls nicht kopiert) + +```bash +mkdir -p mosquitto/{config,data,log} + +cat > mosquitto/config/mosquitto.conf << 'EOF' +listener 1883 +allow_anonymous true + +listener 9001 +protocol websockets + +persistence true +persistence_location /mosquitto/data/ + +log_dest file /mosquitto/log/mosquitto.log +EOF + +sudo chown -R 1883:1883 mosquitto/data mosquitto/log +chmod 755 mosquitto/config mosquitto/data mosquitto/log +``` + +### 7. Environment (.env) prüfen/anpassen + +```bash +nano .env +# Prüfen u.a.: +# DB_HOST=db +# DB_CONN=mysql+pymysql://${DB_USER}:${DB_PASSWORD}@db/${DB_NAME} +# VITE_API_URL=https://YOUR_SERVER_HOST/api +# Sichere Passwörter & Secrets setzen +``` + +Hinweise: +- Vorlage `.env.example` aus dem Repository verwenden: `cp .env.example .env` (falls noch nicht vorhanden). +- In Produktion lädt der Code keine `.env` automatisch (nur bei `ENV=development`). + +--- + +## 🚀 Phase 3: System-Start und Konfiguration + +### 8. Images von Registry pullen + +```bash +echo $GITHUB_TOKEN | docker login ghcr.io -u robbstarkaustria --password-stdin +docker compose -f docker-compose.prod.yml pull +``` + +### 9. System starten + +```bash +docker compose -f docker-compose.prod.yml up -d +docker compose ps +docker compose logs -f +``` + +### 10. Firewall konfigurieren + +Debian hat standardmäßig nftables/iptables aktiv. Falls eine einfache Verwaltung gewünscht ist, kann `ufw` installiert werden: + +```bash +sudo apt install -y ufw +sudo ufw allow ssh +sudo ufw allow 80/tcp +sudo ufw allow 443/tcp +sudo ufw allow 1883/tcp +sudo ufw allow 9001/tcp +sudo ufw enable +sudo ufw status +``` + +Alternativ direkt via nftables / iptables konfigurieren (optional, nicht dargestellt). + +### 11. Installation validieren + +```bash +curl http://localhost/api/health +curl -k https://localhost # -k bei selbstsignierten Zertifikaten + +docker compose ps +docker compose logs server +docker compose logs mqtt +``` + +--- + +## 🧪 Quickstart (lokale Entwicklung) + +```bash +cp -n .env.example .env +docker compose up -d --build +docker compose ps +docker compose logs -f server +``` + +Dev-Erreichbarkeit: +- Dashboard: http://localhost:5173 +- API: http://localhost:8000/api +- Health: http://localhost:8000/health +- Screenshots: http://localhost:8000/screenshots/.jpg +- MQTT: localhost:1883 (WebSocket: 9001) + +### 12. Systemd Autostart (optional) + +```bash +sudo tee /etc/systemd/system/infoscreen.service > /dev/null << 'EOF' +[Unit] +Description=Infoscreen Application +Requires=docker.service +After=docker.service + +[Service] +Type=oneshot +RemainAfterExit=yes +WorkingDirectory=/home/$USER/infoscreen-deployment +ExecStart=/usr/bin/docker compose -f docker-compose.prod.yml up -d +ExecStop=/usr/bin/docker compose -f docker-compose.prod.yml down +TimeoutStartSec=300 + +[Install] +WantedBy=multi-user.target +EOF + +sudo systemctl enable infoscreen.service +sudo systemctl start infoscreen.service +``` + +--- + +## 🌐 Zugriff auf die Anwendung + +- HTTPS Dashboard: `https://YOUR_SERVER_IP` +- HTTP (Redirect): `http://YOUR_SERVER_IP` +- API: `http://YOUR_SERVER_IP/api/` +- MQTT: `YOUR_SERVER_IP:1883` +- MQTT WebSocket: `YOUR_SERVER_IP:9001` + +--- + +## 🔧 Troubleshooting + +```bash +docker compose ps +docker compose logs -f server +docker compose restart server +``` + +Häufige Ursachen: + +| Problem | Lösung | +|---------|--------| +| Container startet nicht | `docker compose logs ` prüfen | +| Ports belegt | `ss -tulpn | grep -E ':80|:443|:1883|:9001'` | +| Keine Berechtigung Docker | User zur Gruppe `docker` hinzufügen & neu einloggen | +| DB-Verbindung schlägt fehl | `.env` Einträge prüfen (Host = db) | +| Mosquitto Fehler | Ordner-Berechtigungen (`1883:1883`) prüfen | + +System Neustart / Update des Stacks: + +```bash +docker compose down +docker compose pull +docker compose up -d +``` + +--- + +## 📝 Wartung + +### Updates + +```bash +docker compose pull +docker compose up -d +sudo apt update && sudo apt upgrade -y +``` + +### Backup (abhängig von persistenter Datenhaltung – hier nur Mosquitto + Certs exemplarisch) + +```bash +docker compose down +sudo tar -czf infoscreen-backup-$(date +%Y%m%d).tar.gz mosquitto/data/ certs/ + +# Wiederherstellung +sudo tar -xzf infoscreen-backup-YYYYMMDD.tar.gz +docker compose up -d +``` + +--- + +**Das Infoscreen-System ist jetzt auf Ihrem Debian-Server bereitgestellt.** + +Bei Verbesserungswünschen oder Problemen: Issues / Pull Requests im Repository willkommen. diff --git a/deployment-ubuntu.md b/deployment-ubuntu.md new file mode 100644 index 0000000..17ec555 --- /dev/null +++ b/deployment-ubuntu.md @@ -0,0 +1,417 @@ +# Infoscreen Deployment Guide + +Komplette Anleitung für das Deployment des Infoscreen-Systems auf einem Ubuntu-Server mit GitHub Container Registry. + +## 📋 Übersicht + +- **Phase 0**: Docker Installation (optional) +- **Phase 1**: Images bauen und zur Registry pushen +- **Phase 2**: Ubuntu-Server Installation +- **Phase 3**: System-Konfiguration und Start + +--- + +## 🐳 Phase 0: Docker Installation (optional) + +Falls Docker noch nicht installiert ist, wählen Sie eine der folgenden Optionen: + +### Option A: Ubuntu Repository (schnell) + +```bash +# Standard Ubuntu Docker-Pakete +sudo apt update +sudo apt install docker.io docker-compose-plugin -y +sudo systemctl enable docker +sudo systemctl start docker +``` + +### Option B: Offizielle Docker-Installation (empfohlen) + +```bash +# Alte Docker-Versionen entfernen +sudo apt remove docker docker-engine docker.io containerd runc -y + +# Abhängigkeiten installieren +sudo apt update +sudo apt install ca-certificates curl gnupg lsb-release -y + +# Docker GPG-Key hinzufügen +sudo mkdir -p /etc/apt/keyrings +curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg + +# Docker Repository hinzufügen +echo \ + "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ + $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null + +# Docker installieren (neueste Version) +sudo apt update +sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y + +# Docker aktivieren und starten +sudo systemctl enable docker +sudo systemctl start docker + +# User zur Docker-Gruppe hinzufügen +sudo usermod -aG docker $USER + +# Neuanmeldung für Gruppenänderung erforderlich +exit +# Neu einloggen via SSH +``` + +### Docker-Installation testen + +```bash +# Test-Container ausführen +docker run hello-world + +# Docker-Version prüfen +docker --version +docker compose version +``` + +--- + +## 🏗️ Phase 1: Images bauen und pushen (Entwicklungsmaschine) + +### 1. GitHub Container Registry Login + +```bash +# GitHub Personal Access Token mit write:packages Berechtigung erstellen +echo $GITHUB_TOKEN | docker login ghcr.io -u robbstarkaustria --password-stdin + +# Oder interaktiv: +docker login ghcr.io +# Username: robbstarkaustria +# Password: [GITHUB_TOKEN] +``` + +### 2. Images bauen und taggen + +```bash +cd /workspace + +# Server-Image bauen +docker build -f server/Dockerfile -t ghcr.io/robbstarkaustria/infoscreen-api:latest . + +# Dashboard-Image bauen +docker build -f dashboard/Dockerfile -t ghcr.io/robbstarkaustria/infoscreen-dashboard:latest . + +# Listener-Image bauen (falls vorhanden) +docker build -f listener/Dockerfile -t ghcr.io/robbstarkaustria/infoscreen-listener:latest . + +# Scheduler-Image bauen (falls vorhanden) +docker build -f scheduler/Dockerfile -t ghcr.io/robbstarkaustria/infoscreen-scheduler:latest . +``` + +### 3. Images zur Registry pushen + +```bash +# Alle Images pushen +docker push ghcr.io/robbstarkaustria/infoscreen-api:latest +docker push ghcr.io/robbstarkaustria/infoscreen-dashboard:latest +docker push ghcr.io/robbstarkaustria/infoscreen-listener:latest +docker push ghcr.io/robbstarkaustria/infoscreen-scheduler:latest + +# Status prüfen +docker images | grep ghcr.io +``` + +--- + +## 🖥️ Phase 2: Ubuntu-Server Installation + +### 4. Ubuntu Server vorbereiten + +```bash +sudo apt update && sudo apt upgrade -y + +# Grundlegende Tools installieren +sudo apt install git curl wget -y + +# Docker installieren (siehe Phase 0) +``` + +### 5. Deployment-Dateien übertragen + +```bash +# Deployment-Ordner erstellen +mkdir -p ~/infoscreen-deployment +cd ~/infoscreen-deployment + +# Dateien vom Dev-System kopieren (über SCP) +scp user@dev-machine:/workspace/docker-compose.prod.yml . +scp user@dev-machine:/workspace/.env . +scp user@dev-machine:/workspace/nginx.conf . +scp -r user@dev-machine:/workspace/certs ./ +scp -r user@dev-machine:/workspace/mosquitto ./ + +# Alternative: Deployment-Paket verwenden +# Auf Dev-Maschine (/workspace): +# tar -czf infoscreen-deployment.tar.gz docker-compose.prod.yml .env nginx.conf certs/ mosquitto/ +# scp infoscreen-deployment.tar.gz user@server:~/ +# Auf Server: tar -xzf infoscreen-deployment.tar.gz +``` + +### 6. Mosquitto-Konfiguration vorbereiten + +```bash +# Falls mosquitto-Ordner noch nicht vollständig vorhanden: +mkdir -p mosquitto/{config,data,log} + +# Mosquitto-Konfiguration erstellen (falls nicht übertragen) +cat > mosquitto/config/mosquitto.conf << 'EOF' +# ----------------------------- +# Netzwerkkonfiguration +# ----------------------------- +listener 1883 +allow_anonymous true +# password_file /mosquitto/config/passwd + +# WebSocket (optional) +listener 9001 +protocol websockets + +# ----------------------------- +# Persistence & Pfade +# ----------------------------- +persistence true +persistence_location /mosquitto/data/ + +log_dest file /mosquitto/log/mosquitto.log +EOF + +# Berechtigungen für Mosquitto setzen +sudo chown -R 1883:1883 mosquitto/data mosquitto/log +chmod 755 mosquitto/config mosquitto/data mosquitto/log +``` + +### 7. Environment-Variablen anpassen + +```bash +# .env für Produktionsumgebung anpassen +nano .env + +# Wichtige Anpassungen: +# VITE_API_URL=https://YOUR_SERVER_HOST/api # Für Dashboard-Build (Production) +# DB_HOST=db # In Containern immer 'db' +# DB_CONN=mysql+pymysql://${DB_USER}:${DB_PASSWORD}@db/${DB_NAME} +# Alle Passwörter für Produktion ändern +``` + +Hinweise: +- Eine Vorlage `.env.example` liegt im Repo. Kopiere sie als Ausgangspunkt: `cp .env.example .env`. +- Für lokale Entwicklung lädt `server/database.py` die `.env`, wenn `ENV=development` gesetzt ist. +- In Produktion verwaltet Compose/Container die Variablen; kein automatisches `.env`-Load im Code nötig. + +--- + +## 🚀 Phase 3: System-Start und Konfiguration + +### 8. Images von Registry pullen + +```bash +# GitHub Container Registry Login (falls private Repository) +echo $GITHUB_TOKEN | docker login ghcr.io -u robbstarkaustria --password-stdin + +# Images pullen +docker compose -f docker-compose.prod.yml pull +``` + +### 9. System starten + +```bash +# Container starten +docker compose -f docker-compose.prod.yml up -d + +# Status prüfen +docker compose ps +docker compose logs -f +``` + +### 10. Firewall konfigurieren + +```bash +sudo ufw enable +sudo ufw allow ssh +sudo ufw allow 80/tcp +sudo ufw allow 443/tcp +sudo ufw allow 1883/tcp # MQTT +sudo ufw allow 9001/tcp # MQTT WebSocket +sudo ufw status +``` + +### 11. Installation validieren + +```bash +# Health-Checks +curl http://localhost/api/health +curl https://localhost -k # -k für selbstsignierte Zertifikate + +# Container-Status +docker compose ps + +# Logs bei Problemen anzeigen +docker compose logs server +docker compose logs dashboard +docker compose logs mqtt +``` + +--- + +## 🧪 Quickstart (Entwicklung) + +Schneller Start der Entwicklungsumgebung mit automatischen Proxys und Hot-Reload. + +```bash +# Im Repository-Root +# 1) .env aus Vorlage erzeugen (lokal, falls noch nicht vorhanden) +cp -n .env.example .env + +# 2) Dev-Stack starten (verwendet docker-compose.yml + docker-compose.override.yml) +docker compose up -d --build + +# 3) Status & Logs +docker compose ps +docker compose logs -f server +docker compose logs -f dashboard +docker compose logs -f mqtt + +# 4) Stack stoppen +docker compose down +``` + +Erreichbarkeit (Dev): +- Dashboard (Vite): http://localhost:5173 +- API (Flask Dev): http://localhost:8000/api +- API Health: http://localhost:8000/health +- Screenshots: http://localhost:8000/screenshots/.jpg +- MQTT: localhost:1883 (WebSocket: localhost:9001) + +Hinweise: +- `ENV=development` lädt `.env` automatisch in `server/database.py`. +- Vite proxy routet `/api` und `/screenshots` in Dev direkt auf die API (siehe `dashboard/vite.config.ts`). + +### 12. Automatischer Start (optional) + +```bash +# Systemd-Service erstellen +sudo tee /etc/systemd/system/infoscreen.service > /dev/null << 'EOF' +[Unit] +Description=Infoscreen Application +Requires=docker.service +After=docker.service + +[Service] +Type=oneshot +RemainAfterExit=yes +WorkingDirectory=/home/$USER/infoscreen-deployment +ExecStart=/usr/bin/docker compose -f docker-compose.prod.yml up -d +ExecStop=/usr/bin/docker compose -f docker-compose.prod.yml down +TimeoutStartSec=300 + +[Install] +WantedBy=multi-user.target +EOF + +# Service aktivieren +sudo systemctl enable infoscreen.service +sudo systemctl start infoscreen.service +``` + +--- + +## 🌐 Zugriff auf die Anwendung + +Nach erfolgreichem Deployment ist die Anwendung unter folgenden URLs erreichbar: + +- **HTTPS Dashboard**: `https://YOUR_SERVER_IP` +- **HTTP Dashboard**: `http://YOUR_SERVER_IP` (Redirect zu HTTPS) +- **API**: `http://YOUR_SERVER_IP/api/` +- **MQTT**: `YOUR_SERVER_IP:1883` +- **MQTT WebSocket**: `YOUR_SERVER_IP:9001` + +--- + +## 🔧 Troubleshooting + +### Container-Status prüfen + +```bash +# Alle Container anzeigen +docker compose ps + +# Spezifische Logs anzeigen +docker compose logs -f [service-name] + +# Container einzeln neustarten +docker compose restart [service-name] +``` + +### System neustarten + +```bash +# Komplett neu starten +docker compose down +docker compose up -d + +# Images neu pullen +docker compose pull +docker compose up -d +``` + +### Häufige Probleme + +| Problem | Lösung | +|---------|--------| +| Container startet nicht | `docker compose logs [service]` prüfen | +| Ports bereits belegt | `sudo netstat -tulpn \| grep :80` prüfen | +| Keine Berechtigung | User zu docker-Gruppe hinzufügen | +| DB-Verbindung fehlschlägt | Environment-Variablen in `.env` prüfen | +| Mosquitto startet nicht | Ordner-Berechtigungen für `1883:1883` setzen | + +--- + +## 📊 Docker-Version Vergleich + +| Aspekt | Ubuntu Repository | Offizielle Installation | +|--------|------------------|------------------------| +| **Installation** | ✅ Schnell (1 Befehl) | ⚠️ Mehrere Schritte | +| **Version** | ⚠️ Oft älter | ✅ Neueste Version | +| **Updates** | ✅ Via apt | ✅ Via apt (nach Setup) | +| **Stabilität** | ✅ Getestet | ✅ Aktuell | +| **Features** | ⚠️ Möglicherweise eingeschränkt | ✅ Alle Features | + +**Empfehlung:** Für Produktion die offizielle Docker-Installation verwenden. + +--- + +## 📝 Wartung + +### Regelmäßige Updates + +```bash +# Images aktualisieren +docker compose pull +docker compose up -d + +# System-Updates +sudo apt update && sudo apt upgrade -y +``` + +### Backup + +```bash +# Container-Daten sichern +docker compose down +sudo tar -czf infoscreen-backup-$(date +%Y%m%d).tar.gz mosquitto/data/ certs/ + +# Backup wiederherstellen +sudo tar -xzf infoscreen-backup-YYYYMMDD.tar.gz +docker compose up -d +``` + +--- + +**Das Infoscreen-System ist jetzt vollständig über GitHub