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

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.