enerport-web-app/docker/GITEA_SETUP.md

Gitea CI/CD Setup

Diese Anleitung erklärt, wie Sie die benötigten Variables und Secrets in Gitea für den automatischen Build und Push Workflow einrichten.

Gitea Workflow

Der Workflow .gitea/workflows/build-and-push.yaml wird automatisch ausgeführt und:

1. Bestimmt automatisch den Image-Tag basierend auf dem Commit/Tag
2. Baut das Docker Image
3. Pusht das Image zur Gitea Registry

Automatische Tag-Generierung

Der IMAGE_TAG wird automatisch bestimmt:

Trigger	Tag-Format	Beispiel
Push auf main Branch	latest	latest
Git Tag (v*)	Tag-Name	v1.0.0, v2.1.3
Andere Branches	{branch}-{sha}	develop-a1b2c3d

Sie müssen IMAGE_TAG NICHT mehr als Variable setzen - es wird automatisch generiert!

Benötigte Gitea Variables und Secrets

Variables (öffentlich)

Navigieren Sie zu: Settings → Actions → Variables

Erstellen Sie folgende Variables:

Name	Wert	Beispiel
REGISTRY_URL	URL der Gitea Registry	gitea.moz-tech.de
NAMESPACE	Namespace/Benutzer	murat
REPO_NAME	Repository Name	enerport-web-app
CONTAINER_PORT	Port auf dem Zielserver	8080 oder 80

Hinweise:

• IMAGE_TAG wird automatisch aus dem Commit/Tag generiert und muss nicht als Variable gesetzt werden
• CONTAINER_PORT definiert den Host-Port auf dem Zielserver (Container-intern ist immer Port 8080)

Secrets (vertraulich)

Navigieren Sie zu: Settings → Actions → Secrets

Erstellen Sie folgende Secrets:

Registry Authentifizierung

Name	Wert	Beispiel
CI_GITEA_USER	Gitea Benutzername	murat
CI_GITEA_TOKEN	Gitea Access Token	74a7738116bfb99497a7781291efc5766901f497

Deployment (SSH)

Name	Wert	Beispiel
DEPLOY_HOST	Hostname/IP des Zielservers	server.example.com oder 192.168.1.100
DEPLOY_USER	SSH Benutzername	deploy oder root
DEPLOY_SSH_PRIVATE_KEY	SSH Private Key	-----BEGIN OPENSSH PRIVATE KEY-----\n...

Hinweise:

• User und Token werden zusammen als Secrets gespeichert für eine sichere Authentifizierung
• Der Prefix CI_GITEA_ ist erforderlich, da Gitea keine Variablen mit dem Prefix GITEA_ erlaubt
• Der SSH Private Key muss im OpenSSH-Format vorliegen

SSH-Key für Deployment erstellen

1. SSH-Schlüsselpaar generieren (auf Ihrem lokalen Rechner)

ssh-keygen -t ed25519 -C "gitea-deploy" -f ~/.ssh/gitea_deploy_key

Dies erstellt:

• ~/.ssh/gitea_deploy_key (Private Key) - Für Gitea Secret
• ~/.ssh/gitea_deploy_key.pub (Public Key) - Für Zielserver

2. Public Key auf Zielserver hinzufügen

Kopieren Sie den Public Key auf den Zielserver:

ssh-copy-id -i ~/.ssh/gitea_deploy_key.pub user@server.example.com

Oder manuell:

# Public Key anzeigen
cat ~/.ssh/gitea_deploy_key.pub

# Auf dem Zielserver in ~/.ssh/authorized_keys einfügen

3. Private Key als Secret hinzufügen

# Private Key anzeigen
cat ~/.ssh/gitea_deploy_key

Kopieren Sie den gesamten Inhalt (inklusive -----BEGIN und -----END Zeilen) und fügen Sie ihn als Secret DEPLOY_SSH_PRIVATE_KEY in Gitea ein.

4. Voraussetzungen auf dem Zielserver

Der Zielserver muss folgendes installiert haben:

• Docker
• SSH-Server

Stellen Sie sicher, dass der Deploy-User Docker-Befehle ausführen darf:

# Auf dem Zielserver:
sudo usermod -aG docker deploy-user

Docker Network:

• Der Container wird automatisch dem Docker-Netzwerk proxy hinzugefügt
• Das Netzwerk wird beim ersten Deployment automatisch erstellt, falls es nicht existiert
• Dies ermöglicht die Integration mit Reverse-Proxies wie Traefik oder Nginx Proxy Manager

Access Token erstellen

1. Navigieren Sie zu Settings → Applications → Manage Access Tokens
2. Klicken Sie auf Generate New Token
3. Geben Sie einen Namen ein (z.B. "Docker Registry")
4. Wählen Sie die Berechtigung: write:package (für Registry Push)
5. Klicken Sie auf Generate Token
6. Kopieren Sie den Token und fügen Sie ihn als Secret CI_GITEA_TOKEN hinzu

Workflow und Deployment

Der Workflow besteht aus zwei Jobs:

Job 1: Build and Push

1. ✅ Checkout Code
2. ✅ Image Tag bestimmen (automatisch)
3. ✅ Docker Image bauen
4. ✅ Image zur Registry pushen

Job 2: Deploy (läuft nach erfolgreichem Build)

1. ✅ SSH-Verbindung zum Zielserver aufbauen
2. ✅ Login zur Docker Registry auf dem Zielserver
3. ✅ Neues Image pullen
4. ✅ Alten Container stoppen und entfernen
5. ✅ Docker-Netzwerk 'proxy' prüfen/erstellen
6. ✅ Neuen Container starten (Network: proxy, Port: CONTAINER_PORT:8080, auto-restart)

Workflow testen

Nach der Einrichtung der Variables und Secrets:

Test 1: Push auf main Branch (baut, pusht und deployt 'latest')

git add .
git commit -m "Test CI/CD workflow with deployment"
git push origin main

→ Erstellt Image: gitea.moz-tech.de/murat/enerport-web-app:latest
→ Deployed auf: http://<DEPLOY_HOST>:<CONTAINER_PORT>

Test 2: Git Tag erstellen (baut, pusht und deployt versioniertes Image)

git tag v1.0.0
git push origin v1.0.0

→ Erstellt Image: gitea.moz-tech.de/murat/enerport-web-app:v1.0.0
→ Deployed auf: http://<DEPLOY_HOST>:<CONTAINER_PORT>

Workflow-Status überprüfen:

• Navigieren Sie zu Actions in Ihrem Gitea Repository
• Sie sollten den Workflow "Build and Push Docker Image" sehen
• Der Workflow zeigt zwei Jobs: build-and-push und deploy
• Klicken Sie auf die Jobs, um detaillierte Logs zu sehen

Deployment verifizieren:

# Auf dem Zielserver prüfen:
ssh user@server.example.com "docker ps | grep enerport-web-app"

# Oder im Browser:
# http://<DEPLOY_HOST>:<CONTAINER_PORT>

Port-Mapping:

• Container-intern läuft die App immer auf Port 8080
• Auf dem Zielserver ist die App unter CONTAINER_PORT erreichbar
• Beispiel: CONTAINER_PORT=80 → App erreichbar unter http://server.example.com

Docker Network:

• Der Container wird automatisch dem Netzwerk proxy hinzugefügt
• Dies ermöglicht die Kommunikation mit Reverse-Proxies (z.B. Traefik, Nginx Proxy Manager)
• Das Netzwerk wird beim ersten Deployment automatisch erstellt

Troubleshooting

Fehler: "REGISTRY_URL not set in .env"

→ Stellen Sie sicher, dass alle Variables korrekt in Gitea eingerichtet sind

Fehler: "Failed to login to registry"

→ Überprüfen Sie das GITEA_TOKEN Secret und stellen Sie sicher, dass es die write:package Berechtigung hat

Fehler: "Image not found locally"

→ Der Build-Schritt ist fehlgeschlagen. Überprüfen Sie die Build-Logs im Workflow

Lokale Entwicklung vs. CI/CD

Lokal:

• Verwendet die docker/.env Datei
• Manuelle Ausführung von ./build.sh und ./push.sh

CI/CD (Gitea):

• Erstellt .env Datei automatisch aus Gitea Variables/Secrets
• Automatische Ausführung bei jedem Push auf main

Sicherheit

⚠️ Wichtig:

• Committen Sie die docker/.env Datei NIEMALS in Git (bereits in .gitignore)
• Das GITEA_TOKEN sollte nur als Secret gespeichert werden
• Alle anderen Werte können als Variables gespeichert werden

Image Pull

Nach erfolgreichem Push können Sie das Image wie folgt pullen:

# Login zur Registry
docker login gitea.moz-tech.de -u murat

# Image pullen
docker pull gitea.moz-tech.de/murat/enerport-web-app:latest

# Container starten
docker run -p 8080:8080 gitea.moz-tech.de/murat/enerport-web-app:latest