diff --git a/docs/FORGEJO_SETUP.md b/docs/FORGEJO_SETUP.md new file mode 100644 index 0000000..f06663a --- /dev/null +++ b/docs/FORGEJO_SETUP.md @@ -0,0 +1,274 @@ +# 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 \ + --name insight-runner \ + --labels ubuntu-latest:docker://node:20 + +# Alternativ: non-interaktiv +forgejo-runner register --no-interactive \ + --instance https://git.xinion.lan \ + --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 +# 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