INSIGHT-MVP/docs/FORGEJO_SETUP.md

# Forgejo Setup - Anleitung fuer den Git-Server

> **Ziel:** Forgejo so konfigurieren, dass CI/CD Pipelines (Forgejo Actions)
> automatisch laufen und Docker Images in die integrierte Container Registry
> gepusht werden.

---

## 1. Voraussetzungen pruefen

### 1.1 Forgejo Actions aktiviert?

Forgejo Actions ist seit Forgejo 1.21+ verfuegbar, muss aber in der
Server-Konfiguration aktiviert sein.

In der Forgejo-Konfiguration (`app.ini` auf dem Git-Server) pruefen:

```ini
# /etc/forgejo/app.ini (oder wo Forgejo installiert ist)

[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = https://code.forgejo.org
```

Falls nicht vorhanden: Eintrag hinzufuegen und Forgejo neustarten.

```bash
sudo systemctl restart forgejo
```

### 1.2 Container Registry aktiviert?

Die Registry muss ebenfalls in `app.ini` aktiviert sein:

```ini
[packages]
ENABLED = true
```

---

## 2. Forgejo Actions Runner einrichten

Forgejo Actions braucht einen **Runner** (vergleichbar mit GitHub Actions
Self-Hosted Runner). Der Runner fuehrt die CI/CD-Jobs aus.

### 2.1 Runner auf dem Git-Server installieren

```bash
# Runner-Binary herunterladen (aktuelle Version pruefen auf:
# https://code.forgejo.org/forgejo/runner/releases)

# Beispiel fuer Linux x86_64:
wget https://code.forgejo.org/forgejo/runner/releases/download/v4.0.0/forgejo-runner-4.0.0-linux-amd64
chmod +x forgejo-runner-4.0.0-linux-amd64
sudo mv forgejo-runner-4.0.0-linux-amd64 /usr/local/bin/forgejo-runner
```

### 2.2 Runner registrieren

Zuerst ein **Registration Token** in Forgejo generieren:

1. Forgejo Web-UI oeffnen: `https://git.xinion.lan`
2. **Site Administration** > **Runners** (oben rechts Zahnrad-Icon)
3. Oder: **Repository** > **Settings** > **Actions** > **Runners**
4. Klick auf **"Create new Runner"** oder **"Registration Token"**
5. Token kopieren

Dann auf dem Server den Runner registrieren:

```bash
# Runner registrieren (interaktiv)
forgejo-runner register \
  --instance https://git.xinion.lan \
  --token <DEIN-REGISTRATION-TOKEN> \
  --name insight-runner \
  --labels ubuntu-latest:docker://node:20

# Alternativ: non-interaktiv
forgejo-runner register --no-interactive \
  --instance https://git.xinion.lan \
  --token <DEIN-REGISTRATION-TOKEN> \
  --name insight-runner \
  --labels "ubuntu-latest:docker://node:20,docker:docker://docker:latest"
```

### 2.3 Runner als Systemd-Service einrichten

```bash
# Service-Datei erstellen
sudo tee /etc/systemd/system/forgejo-runner.service > /dev/null << 'UNIT'
[Unit]
Description=Forgejo Actions Runner
After=docker.service

[Service]
Type=simple
User=forgejo-runner
WorkingDirectory=/opt/forgejo-runner
ExecStart=/usr/local/bin/forgejo-runner daemon
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
UNIT

# User und Verzeichnis anlegen
sudo useradd -r -s /bin/false forgejo-runner
sudo mkdir -p /opt/forgejo-runner
sudo chown forgejo-runner:forgejo-runner /opt/forgejo-runner

# Docker-Zugriff fuer den Runner
sudo usermod -aG docker forgejo-runner

# Service starten
sudo systemctl daemon-reload
sudo systemctl enable forgejo-runner
sudo systemctl start forgejo-runner

# Status pruefen
sudo systemctl status forgejo-runner
```

### 2.4 Pruefen ob Runner aktiv ist

In Forgejo Web-UI:
- **Site Administration** > **Runners**
- Der Runner `insight-runner` sollte mit Status **"Online"** erscheinen

---

## 3. Repository-Einstellungen

### 3.1 Actions fuer das Repository aktivieren

1. Repository oeffnen: `https://git.xinion.lan/gitadmin/INSIGHT-MVP`
2. **Settings** > **Repository**
3. Unter **"Actions"**: Haken setzen bei **"Enable Repository Actions"**
4. Speichern

### 3.2 Repository Secrets anlegen

Die CI/CD-Pipeline braucht Secrets fuer den Server-Zugang.

1. **Settings** > **Actions** > **Secrets**
2. Folgende Secrets anlegen:

| Secret Name         | Wert                                                    | Zweck                       |
|---------------------|---------------------------------------------------------|-----------------------------|
| `SSH_DEPLOY_KEY`    | Inhalt von `.keys/cicd_ed25519` (Private Key)           | SSH-Zugriff auf Server      |
| `DEPLOY_HOST`       | IP-Adresse von `insight-dev-01`                         | Server-Adresse              |
| `DEPLOY_USER`       | `deploy`                                                | SSH-User auf dem Server     |
| `REGISTRY_USER`     | Forgejo-Username (z.B. `gitadmin`)                      | Container Registry Login    |
| `REGISTRY_PASSWORD` | Forgejo-Passwort oder Access Token                      | Container Registry Login    |

#### SSH Key als Secret hinterlegen

Den **kompletten** Inhalt des Private Keys kopieren:

```bash
# Auf dem MacBook ausfuehren:
cat .keys/cicd_ed25519
```

Den gesamten Output (inkl. `-----BEGIN OPENSSH PRIVATE KEY-----` und
`-----END OPENSSH PRIVATE KEY-----`) in das Secret-Feld einfuegen.

#### Forgejo Access Token erstellen (fuer Registry)

Statt Passwort empfehlen wir einen **Access Token**:

1. Forgejo Web-UI > **Profil** (oben rechts) > **Settings** > **Applications**
2. **Generate New Token**
3. Name: `insight-registry`
4. Berechtigungen: `write:package` (oder `package` Scope)
5. Token kopieren und als `REGISTRY_PASSWORD` Secret anlegen

### 3.3 Branch Protection einrichten

1. **Settings** > **Branches**
2. **Add Branch Protection Rule**

Fuer `main`:
- **Branch name pattern:** `main`
- **Enable push:** Deaktiviert (nur via Merge)
- **Required approvals:** 1
- **Status checks must pass:** Aktiviert

Fuer `develop`:
- **Branch name pattern:** `develop`
- **Enable push:** Deaktiviert (nur via Merge)
- **Required approvals:** 1
- **Status checks must pass:** Aktiviert

---

## 4. Container Registry testen

### 4.1 Vom MacBook aus testen

```bash
# In die Forgejo Registry einloggen
docker login git.xinion.lan -u <FORGEJO-USERNAME>
# Passwort oder Access Token eingeben

# Test-Image taggen und pushen
docker pull hello-world
docker tag hello-world git.xinion.lan/gitadmin/insight-test:latest
docker push git.xinion.lan/gitadmin/insight-test:latest

# Aufraumen
docker rmi git.xinion.lan/gitadmin/insight-test:latest
```

### 4.2 In Forgejo pruefen

1. Repository > **Packages** Tab
2. Das `insight-test` Image sollte sichtbar sein
3. Nach dem Test kann es geloescht werden

---

## 5. Checkliste

Bitte alle Punkte abarbeiten und abhaken:

- [ ] `app.ini`: `[actions] ENABLED = true` gesetzt
- [ ] `app.ini`: `[packages] ENABLED = true` gesetzt
- [ ] Forgejo neugestartet nach Config-Aenderung
- [ ] Forgejo Runner installiert und registriert
- [ ] Runner laeuft als Systemd-Service und ist "Online"
- [ ] Repository Actions aktiviert (Settings > Repository)
- [ ] Secret `SSH_DEPLOY_KEY` angelegt (CI/CD Private Key)
- [ ] Secret `DEPLOY_HOST` angelegt (Server-IP)
- [ ] Secret `DEPLOY_USER` angelegt (`deploy`)
- [ ] Secret `REGISTRY_USER` angelegt (Forgejo Username)
- [ ] Secret `REGISTRY_PASSWORD` angelegt (Access Token)
- [ ] Branch Protection fuer `main` eingerichtet
- [ ] Branch Protection fuer `develop` eingerichtet
- [ ] Container Registry getestet (docker push/pull funktioniert)

---

## 6. Haeufige Probleme

### Runner startet nicht
```bash
# Logs pruefen
sudo journalctl -u forgejo-runner -f

# Hat der Runner Docker-Zugriff?
sudo -u forgejo-runner docker ps
```

### Actions werden nicht getriggert
- Ist Actions im Repository aktiviert? (Settings > Repository)
- Liegt die Workflow-Datei unter `.forgejo/workflows/`?
- Ist der Runner online? (Site Administration > Runners)

### Registry Push schlaegt fehl
```bash
# Login testen
docker login git.xinion.lan

# Ist die Registry aktiviert?
# In app.ini: [packages] ENABLED = true
```

### Branch Protection blockiert Push
- Korrekt! Main und Develop sind geschuetzt.
- Feature-Branches erstellen: `git checkout -b feature/mein-feature`
- Push auf Feature-Branch, dann Pull Request erstellen