Run PocketBase as a compose stack, tests included, without Testcontainers

docs/deployment.md

@@ -4,11 +4,14 @@ How a new version of the website ends up on Unraid. Current state:
 **manual** — build the image locally, push it to the Gitea registry, pull it on
 Unraid. Automation via Gitea Actions comes later.
 
-> **Test vs. production.** As long as the domain has not moved yet and NPM is not
-> in front of it, the container runs with a port mapping and is directly reachable
-> on the local network (`http://<unraid>:5000`). In production the mapping is gone
-> — then NPM is the only path to the container. The two compose variants are
-> described separately below.
+The site runs as a **two-container stack** (project `eb-stack`): the Blazor app
+(`eb-blazor`) plus a PocketBase container (`eb-pocketbase`) that holds the
+content. The stack is described by `compose.yaml` (the production base) with
+overlays layered on top.
+
+> **Running it locally is a separate document.** For starting the stack on your
+> own machine and for how the tests run, see `entwicklung.md`. This document is
+> only about getting a built image onto Unraid.
 
 ---
 
@@ -44,13 +47,9 @@ The Docker login then stores the token locally, so it only has to be entered onc
 3. Open a **Pull Request** against `main` in Gitea and merge it there.
 4. Only then build the release image from `main` (below).
 
-**Dev images stay local.** For trying things out on your own machine:
-
-```bash
-scripts/dev-build.sh      # builds elternbeirat-web:dev-<branch>, pushes NOTHING
-```
-
-This way a development state can never accidentally land in the registry as
+**Dev builds stay local.** For trying things out on your own machine, run the
+dev stack (`entwicklung.md`) — it builds the web image from source and pushes
+nothing, so a development state can never accidentally land in the registry as
 `:latest`.
 
 ## Rolling out a new version (manual)
@@ -101,56 +100,31 @@ pitfalls learned from experience:
 
 In the **Compose Manager Plus** plugin (Unraid web interface):
 
-- **Docker** tab → **Compose** section → stack **elternbeirat** →
+- **Docker** tab → **Compose** section → stack **eb-stack** →
   **Compose Down**, then **Compose Up** (or "Pull" + "Up", depending on the plugin
-  version), so that the new `:latest` is pulled.
+  version), so that the new `:latest` is pulled. Only the `eb-blazor` image
+  changes on a deploy; `eb-pocketbase` and its `pb_data` volume stay as they are.
 
 > `docker compose up` does **not** automatically re-pull a `:latest` if an image of
 > the same name is already present locally. When in doubt, explicitly "Pull" first.
 
 ---
 
-## compose variants
+## The compose files
 
-### Test (now: without NPM, directly reachable on the LAN)
+`compose.yaml` is the **production** base and is the file Unraid uses. It defines
+both services with no host port mappings — in production NPM is the only path to
+the web app, and the editors reach PocketBase through an NPM subdomain (see #9).
+`eb-pocketbase` keeps its data on the bind mount
+`/mnt/user/appdata/pocketbase/pb_data`, which only exists on the server.
 
-Present in the repo as `compose.yaml`. Pulls the registry image and maps port
-**5000 → 8080**:
+The two overlays (`compose.dev.yaml`, `compose.test.yaml`) are for local
+development and the tests and are **not** used on Unraid — see `entwicklung.md`.
 
-```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 access, remove in production
-```
-
-Reachable at `http://<unraid>:5000`.
-
-### Production (later: only via NPM)
-
-No `ports:` block, instead the external NPM Docker network:
-
-```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
-```
+> **NPM network (still open).** The base does not yet attach `eb-blazor` to the
+> external NPM Docker network; while the domain has not moved, add a temporary
+> `ports:` mapping (e.g. `5000:8080`) to reach the app on the LAN, and swap it for
+> the `npm` external network once NPM sits in front. Tracked with #9.
 
 ---
 
@@ -162,7 +136,7 @@ which — unlike the moving `:latest` — never shifts. To roll back, replace
 and bring it back up:
 
 ```yaml
-    image: gitea.anticarnist.de/tom/elternbeirat:99dd052   # statt :latest
+    image: gitea.anticarnist.de/tom/elternbeirat:99dd052   # instead of :latest
 ```
 
 Which SHA tags are in the registry is shown by Gitea under
@@ -190,7 +164,7 @@ Requires two repository secrets (Gitea → repo → **Settings** → **Actions**
 The workflow currently only builds and pushes — it does **not** run the tests
 yet, and it does **not** deploy. Those open steps (tests in the workflow,
 auto-deploy with a health gate via Watchtower, encrypting the registry token on
-Unraid) are tracked in `tasks/002-deployment-automatisieren.md`.
+Unraid) are tracked as Gitea issues under the "Elternbeirat-Website" milestone.
 
 Two known pitfalls: the `act_runner` needs Docker socket access to build, and it
 must offer the `ubuntu-latest` label the workflow asks for. To check the runner: