Elternbeirat/docs/deployment.md

# Deployment

Wie ein neuer Stand der Website auf Unraid landet. Aktueller Stand:
**Handbetrieb** — Image lokal bauen, in die Gitea-Registry pushen, auf Unraid
ziehen. Die Automatisierung per Gitea Actions (plan.md Schritt 10) kommt später.

> **Test- vs. Produktivbetrieb.** Solange die Domain noch nicht umgezogen ist und
> NPM nicht davorsteht, läuft der Container mit einem Port-Mapping und ist im
> lokalen Netz direkt erreichbar (`http://<unraid>:5000`). Im Produktivbetrieb
> entfällt das Mapping — dann ist nur NPM der Weg zum Container (plan.md AE-4,
> Abschnitt 8). Die beiden compose-Varianten sind unten getrennt beschrieben.

---

## Voraussetzungen (einmalig)

### Gitea-Registry-Token

Der Push in die Registry braucht ein Gitea-Zugriffstoken mit **Paket-Schreibrecht**
(`package: Read and Write`) — **nicht** das Kontopasswort.

1. Gitea → oben rechts Profilbild → **Settings** → **Applications**.
2. Abschnitt **Manage Access Tokens**: Name vergeben (z.B. `registry-push`).
3. Unter **Select scopes**: `package` auf **Read and Write** stellen.
4. **Generate Token** klicken, Zeichenkette **sofort kopieren** (nur einmal
   sichtbar).

> **Token ist ein Geheimnis.** Niemals in Git, Chats, Screenshots oder Tickets
> im Klartext ablegen. Wird eins doch einmal sichtbar: in Gitea **löschen** und
> neu erzeugen. Ein `package`-Token erlaubt das Hochladen beliebiger Images in
> die Registry.

Der Docker-Login speichert das Token danach lokal, sodass es nur einmal
eingegeben werden muss.

---

## Neuen Stand ausrollen (Handbetrieb)

Alle Befehle auf dem Entwicklungsrechner (Docker installiert), im Repo-Root.

### 1. Image bauen

```bash
docker build -t gitea.anticarnist.de/tom/elternbeirat:latest .
```

Der Image-Pfad ist **kleingeschrieben** — Container-Registries verlangen das im
Pfad, obwohl Benutzer (`Tom`) und Repo (`Elternbeirat`) großgeschrieben sind.

### 2. An der Registry anmelden (einmalig, bis das Token wechselt)

```bash
docker login gitea.anticarnist.de
```

- **Username:** `Tom`
- **Password:** das `package`-Token (nicht das Kontopasswort).

### 3. Image in die Registry pushen

```bash
docker push gitea.anticarnist.de/tom/elternbeirat:latest
```

### 4. Unraid einmalig an der Registry anmelden

Das Image ist **privat**, deshalb muss Unraid sich einmal anmelden, bevor es
ziehen kann. Das **Compose Manager Plus**-Plugin hat dafür kein UI-Feld — der
Login läuft über das Unraid-Terminal (`>_`-Symbol oben rechts in der
Weboberfläche, Prompt `root@Cube:~#`):

```bash
docker login gitea.anticarnist.de
# Username: Tom
# Password: <package-Token>
```

Der Login bleibt gespeichert; er muss nur wiederholt werden, wenn das Token
wechselt. Zwei erfahrungsgemäße Stolpersteine:

- **Nicht mit PowerShell/Laptop verwechseln.** Der Login muss im *Unraid*-Terminal
  passieren (`root@Cube`), nicht in der Windows-PowerShell (`PS C:\`). Der Laptop
  braucht den Login nur zum *Pushen*, Unraid zum *Ziehen*.
- **Falscher Username bleibt hängen.** Meldet der Login „Stored credentials
  invalid or expired" und fragt *nicht* nach dem Namen, erst `docker logout
  gitea.anticarnist.de`, dann neu einloggen — sonst wird versehentlich ein
  Nonsens-Username gespeichert.
- **Klartext-Warnung.** Docker speichert das Token unverschlüsselt in
  `/root/.docker/config.json`. Auf dem eigenen Server für den Anfang okay.
  *Später sauberer:* einen Credential-Helper einrichten (→ offener Punkt unten).

### 5. Auf Unraid neu ziehen und starten

Im **Compose Manager Plus**-Plugin (Unraid-Weboberfläche):

- Reiter **Docker** → Abschnitt **Compose** → Stack **elternbeirat** →
  **Compose Down**, dann **Compose Up** (oder „Pull" + „Up", je nach
  Plugin-Version), damit die neue `:latest` gezogen wird.

> `docker compose up` zieht ein `:latest` **nicht** automatisch neu, wenn schon
> ein gleichnamiges Image lokal liegt. Im Zweifel vorher explizit „Pull".

---

## compose-Varianten

### Test (jetzt: ohne NPM, direkt im LAN erreichbar)

Liegt im Repo als `compose.yaml`. Zieht das Registry-Image und mappt Port
**5000 → 8080**:

```yaml
services:
  eb-web:
    image: gitea.anticarnist.de/tom/elternbeirat:latest
    container_name: eb-web
    restart: unless-stopped
    environment:
      ASPNETCORE_URLS: http://+:8080
      TZ: Europe/Berlin
    ports:
      - "5000:8080"   # TEST-Zugang, im Produktivbetrieb entfernen
```

Erreichbar unter `http://<unraid>:5000`.

### Produktiv (später: nur über NPM)

Kein `ports:`-Block, stattdessen das externe NPM-Docker-Netz (plan.md
Abschnitt 8):

```yaml
services:
  eb-web:
    image: gitea.anticarnist.de/tom/elternbeirat:latest
    container_name: eb-web
    restart: unless-stopped
    environment:
      ASPNETCORE_URLS: http://+:8080
      TZ: Europe/Berlin
    networks: [npm]

networks:
  npm:
    external: true
```

---

## Rollback

`:latest` allein macht Rollback unmöglich — deshalb sobald wir auf Gitea Actions
umstellen (Schritt 10) **immer auch mit dem Commit-SHA taggen** und pushen:

```bash
docker build -t gitea.anticarnist.de/tom/elternbeirat:latest \
             -t gitea.anticarnist.de/tom/elternbeirat:<sha> .
docker push gitea.anticarnist.de/tom/elternbeirat --all-tags
```

Zum Zurückrollen in der Unraid-`compose.yaml` `:latest` durch `:<sha>` des
letzten funktionierenden Stands ersetzen und neu hochfahren.

---

## Offene Automatisierung (später, plan.md Schritt 10)

- `.gitea/workflows/deploy.yml`: auf Push nach `main` bauen und pushen.
- Zwei bekannte Stolpersteine: der `act_runner` braucht Docker-Socket-Zugriff;
  die Registry braucht das `write:package`-Token, nicht das Login-Passwort.
- Redeploy per Watchtower **label-scoped**, sonst aktualisiert er den ganzen
  Home-Lab-Bestand.
- **Registry-Token auf Unraid verschlüsseln:** aktuell liegt es im Klartext in
  `/root/.docker/config.json`. Später einen Credential-Helper einrichten, damit
  die Klartext-Warnung von `docker login` verschwindet.