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. Auf Unraid neu ziehen und starten

Über das **Docker Compose Manager**-Plugin (Unraid-Weboberfläche, kein Terminal):

- Reiter **Docker** → Abschnitt **Compose** → das Projekt **eb-web** →
  **Compose Down**, dann **Compose Up** (oder in der Projekt-UI „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.