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)

```bash
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:

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

Oder manuell:
```bash
# 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

```bash
# 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:
```bash
# 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')
```bash
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)
```bash
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:
```bash
# 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:

```bash
# 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