Add reusable deployment helper

README.md

@@ -71,6 +71,55 @@ docker compose up -d --build
 
 Then open `http://<host>:8091`.
 
+## Deployment helper for published images
+
+For host deployments on this machine, use `deploy/deploy.sh` instead of editing
+compose files by hand. The script is meant to be copied into other repos too: it
+infers the repo name from `origin`, looks up the numeric Gitea repo id via the
+API, computes the host port as `5000 + 10*repo_id + service_number`, copies the
+repo's deployment assets, and writes a ready-to-run deployment directory.
+
+For Arcana FX the Gitea repo id is `4`, so the default deployment port is:
+
+```text
+5000 + 10*4 + 0 = 5040
+```
+
+Generate a deployment directory for a tagged image:
+
+```bash
+./deploy/deploy.sh v0.1.0
+```
+
+That creates `~/deployments/arcana-fx-0/` containing:
+
+- `docker-compose.yml` pinned to `192.168.33.22:3300/gemma/arcana-fx:v0.1.0`
+- `.env` copied from `.env.example` on first run
+- `config/` copied from the repo via `deploy/include-paths.txt`
+- `.deploy.meta` with the resolved repo id, version, and host port
+
+Then edit the generated `.env` and start it:
+
+```bash
+cd ~/deployments/arcana-fx-0
+$EDITOR .env
+docker compose pull
+docker compose up -d
+```
+
+A second service instance can use another service number, which shifts the port
+by 1 while keeping the same repo-id block:
+
+```bash
+./deploy/deploy.sh v0.1.0 1
+# host port becomes 5041
+```
+
+When copying this deployment helper to another repo, update
+`deploy/docker-compose.template.yml` for that app's internal port and mounts,
+and `deploy/include-paths.txt` for any extra files/directories that must travel
+with the generated compose file.
+
 ## Container publishing pipeline
 
 A Gitea Actions workflow lives at `.gitea/workflows/release-container.yml`.