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

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)

docker login gitea.anticarnist.de

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

3. Image in die Registry pushen

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:~#):

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:

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):

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:

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.