diff --git a/compose.yaml b/compose.yaml index 8ed255e..85ad2e8 100644 --- a/compose.yaml +++ b/compose.yaml @@ -1,20 +1,20 @@ -# TEST-Setup fuer den ersten Lauf auf Unraid (ohne NPM, ohne Registry). +# TEST-Setup fuer den ersten Lauf auf Unraid (ohne NPM). +# +# Zieht das fertige Image aus der Gitea-Registry (Build passiert auf dem +# Entwicklungsrechner, siehe docs/deployment.md), statt auf Unraid aus dem +# Quellcode zu bauen. # # Weicht bewusst vom Produktiv-Setup in plan.md Abschnitt 8 ab: -# - Das Image wird hier direkt aus dem Quellcode gebaut (build:), statt aus -# der Gitea-Registry gezogen. Spart Registry + Token fuer den ersten Test. # - Es gibt ein Port-Mapping (5000 aussen -> 8080 innen), damit die App im # lokalen Netz unter http://:5000 erreichbar ist. Im Produktiv- -# betrieb entfaellt das Mapping; dort ist nur NPM der Weg zum Container. +# betrieb entfaellt das Mapping; dort ist nur NPM der Weg zum Container +# (dann stattdessen das externe npm-Netz, siehe docs/deployment.md). # # Sobald NPM steht, wird diese Datei durch das Produktiv-compose ersetzt. services: eb-web: - build: - context: . - dockerfile: Dockerfile - image: elternbeirat-web:test + image: gitea.anticarnist.de/tom/elternbeirat:latest container_name: eb-web restart: unless-stopped environment: diff --git a/docs/deployment.md b/docs/deployment.md new file mode 100644 index 0000000..dbdcfc2 --- /dev/null +++ b/docs/deployment.md @@ -0,0 +1,146 @@ +# 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://: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://: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: . +docker push gitea.anticarnist.de/tom/elternbeirat --all-tags +``` + +Zum Zurückrollen in der Unraid-`compose.yaml` `:latest` durch `:` 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.