# Tessera CI/CD Setup

Runbook fuer die Einrichtung der Gitea-basierten CI/CD-Pipeline.

## Voraussetzungen

- Docker und Docker Compose installiert
- Gitea-Instanz mit aktivierten Actions
- Zugriff auf die Gitea-Administrationsoberflaeche

## 1. Gitea-Repository einrichten

1. In Gitea ein neues Repository erstellen (z.B. `tessera-ctl`)
2. Das Repository als Git-Remote hinzufuegen:

```bash
git remote add origin https://<gitea-url>/<user>/tessera-ctl.git
```

3. In den Repository-Einstellungen unter **Settings > Actions** sicherstellen,
   dass Actions aktiviert ist.

## 2. act_runner registrieren

Der act_runner fuehrt Gitea Actions Workflow-Jobs in Docker-Containern aus.

### Runner-Token generieren

1. In Gitea navigieren zu: **Repository > Settings > Actions > Runners**
   (oder Admin-Panel > Actions > Runners fuer globale Runner)
2. **Create registration token** klicken
3. Token kopieren

### Runner starten

Die Umgebungsvariablen setzen (z.B. in `.env` im Projektverzeichnis oder
direkt in der Shell):

```bash
export GITEA_INSTANCE_URL=https://git.vicolab.de
export GITEA_RUNNER_REGISTRATION_TOKEN=<token-aus-schritt-oben>
```

Runner starten:

```bash
docker compose -f docker-compose.ci.yml up -d
```

Runner-Status pruefen:

```bash
docker compose -f docker-compose.ci.yml logs act_runner
```

Der Runner registriert sich automatisch bei Gitea und ist bereit, Jobs
auszufuehren.

### Bestehender Runner

Wenn bereits ein act_runner als separater Docker-Container laeuft (z.B.
`gitea-runner`), kann `docker-compose.ci.yml` als Dokumentation und Vorlage
fuer eine Neueinrichtung verwendet werden. Der bestehende Runner muss nicht
ersetzt werden.

Bestehenden Runner pruefen:

```bash
docker ps --filter name=gitea-runner
```

## 3. Erforderliche Konfiguration

### Umgebungsvariablen

| Variable | Beschreibung | Wo setzen |
|----------|-------------|-----------|
| `GITEA_INSTANCE_URL` | URL der Gitea-Instanz | `.env` oder Systemumgebung |
| `GITEA_RUNNER_REGISTRATION_TOKEN` | Runner-Registrierungstoken | `.env` oder Systemumgebung |

### Gitea Secrets (fuer die CI-Pipeline)

In Gitea unter **Repository > Settings > Actions > Secrets** koennen Secrets
fuer die Pipeline konfiguriert werden. Aktuell werden keine Secrets in der
Pipeline benoetigt, da Images lokal gebaut und deployed werden (kein Registry-Push).

Falls kuenftig Deploy-Pfade oder Credentials benoetigt werden:

1. In Gitea **Settings > Actions > Secrets** den Secret anlegen
2. In `.gitea/workflows/ci.yml` ueber `${{ secrets.SECRET_NAME }}` referenzieren

**Wichtig:** Secrets niemals in Logs ausgeben oder in Workflow-Dateien
hardcoden.

## 4. Pipeline-Ueberblick

Die CI/CD-Pipeline (`.gitea/workflows/ci.yml`) wird bei jedem Push auf `main`
ausgefuehrt und besteht aus drei aufeinander aufbauenden Jobs:

1. **quality** -- Lint (Biome) und TypeScript Type-Check
2. **test** -- Vitest Unit- und Integrationstests
3. **build-deploy** -- Docker Images bauen und Services neu starten

Ablauf: `quality` -> `test` -> `build-deploy` (jeder Job nur bei Erfolg des
vorherigen).

### Kein Registry-Push

Images werden **lokal auf dem Server gebaut** und nicht in eine Registry
gepusht (D-13). Da der Runner und die Applikation auf demselben Server laufen,
baut die Pipeline die Images direkt mit `docker compose build` und startet die
Services mit `docker compose up -d` neu.

Vorteile:
- Keine Registry-Infrastruktur noetig
- Schnellerer Deploy (kein Push/Pull ueber Netzwerk)
- Einfachere Konfiguration

## 5. Sicherheitshinweise

### Docker Socket

Der act_runner mountet den Host-Docker-Socket (`/var/run/docker.sock`), um Jobs
in Docker-Containern ausfuehren zu koennen. Das bedeutet:

- Der Runner hat Zugriff auf den Docker-Daemon des Hosts
- Er kann Container starten, stoppen und inspizieren

**Risikobewertung:** Akzeptabel fuer interne CI, da:
- Nur Claude pusht manuell bei Meilensteinen (D-11)
- Kein externer Code wird ausgefuehrt
- Ephemeral Mode ist aktiviert (siehe unten)

### Ephemeral Runner

`GITEA_RUNNER_EPHEMERAL=1` sorgt dafuer, dass der Runner seine Credentials
nach jedem Job widerruft und sich neu registriert. Das verhindert:

- Persistente Zugriffstokens im Runner-Container
- Kompromittierung ueber alte Job-Artefakte
- Seitliche Bewegung zwischen Jobs

### Workflow-Dateien

Workflow-Dateien in `.gitea/workflows/` werden direkt aus dem Repository
geladen. Da nur vertrauenswuerdiger Code gepusht wird (D-11, Claude als
einziger Committer), ist das Risiko einer manipulierten Pipeline minimal.

## 6. Fehlerbehebung

### Runner registriert sich nicht

1. Pruefen ob `GITEA_INSTANCE_URL` korrekt und erreichbar ist
2. Token ggf. neu generieren (Token sind einmalig verwendbar bei Ephemeral Mode)
3. Runner-Logs pruefen: `docker compose -f docker-compose.ci.yml logs act_runner`

### Pipeline startet nicht

1. In Gitea pruefen ob Actions fuer das Repository aktiviert ist
2. Pruefen ob der Runner als "online" angezeigt wird (Gitea > Actions > Runners)
3. Sicherstellen dass die Workflow-Datei unter `.gitea/workflows/` liegt
4. YAML-Syntax validieren

### Docker-Build schlaegt fehl

1. Sicherstellen dass `docker-compose.yml` im Arbeitsverzeichnis des Runners
   erreichbar ist
2. Docker Daemon Status pruefen: `docker info`
3. Disk Space pruefen: `df -h`