docs: close the environment contract and de-ambiguate volume derivation (#26)

Review findings on the previous commit: - README's config table listed 8 of the backend's 25 environment variables, omitting the whole DISCORD_* set that the backend refuses to start without. The canonical reference cannot be missing the vars that gate startup. - `docker volume ls --filter name=` is a substring match. Both runbooks used it to find a volume they then mount read-only or delete; a second matching volume makes the mount fail obscurely and the delete take both. Derive the name exactly from the compose project instead. - CUTOVER §6 removes the retired volume 'once the Postgres data has been trusted for a while', in a shell where §1's $VOL no longer exists. - REDEPLOY and DEPLOY still pointed at /opt/bookmarkmanager, so CUTOVER §6's handoff to REDEPLOY §1 sent the operator to a path that does not exist.
2026-08-08 15:50:59 +07:00
parent 01de8903b4
commit 77965c3d76
4 changed files with 53 additions and 25 deletions
@@ -32,10 +32,10 @@ is dropped) — writing it from the spec below costs less than maintaining it
 would.

 Beyond `DEPLOY.md`'s prerequisites (Docker and Compose), this runbook needs
-`python3` — its stdlib `sqlite3` module is the whole SQLite dependency, and it
-stands in for `jq` in §5, which is not installed on the server. It does not have
-to run on the server: §3 only reads the snapshot copy, so it can run on a laptop
-and the resulting `import.sql` be copied over.
+`python3`: its stdlib `sqlite3` module is the whole SQLite dependency, and §5's
+read-path check uses it in place of `jq`, which the server does not have. It
+does not have to run on the server — §3 only reads the snapshot copy, so it can
+run on a laptop and the resulting `import.sql` be copied over.

 ---

@@ -51,9 +51,12 @@ BACKUP_DIR="$(cd .. && pwd)/$(basename "$PWD")-backups"; mkdir -p "$BACKUP_DIR"
 STAMP=$(date -u +%Y%m%d-%H%M%S)

 # The volume is <compose project>_bookmarks-data, and the project name defaults
-# to the lowercased *directory* name, not the repo name — here that makes it
-# mangabookmark_bookmarks-data. Ask Docker instead of typing it out.
-VOL=$(docker volume ls -q --filter name=_bookmarks-data); echo "$VOL"
+# to the lowercased *directory* name, not the repo name — on this host the
+# checkout is ~/mangaBookmark, so the volume is mangabookmark_bookmarks-data.
+# Derive it exactly rather than with a `--filter name=` substring match, which
+# would return every volume whose name merely contains the string.
+VOL="$(basename "$PWD" | tr '[:upper:]' '[:lower:]')_bookmarks-data"
+docker volume inspect "$VOL" >/dev/null && echo "$VOL"

 $COMPOSE stop bookmark-api

@@ -279,8 +282,10 @@ curl -s -H "Authorization: Bearer $TOKEN" $API/bookmarks |

 - **Keep the old SQLite volume for a month.** It is already undeclared in
  compose, so `docker compose down -v` cannot take it. Remove it by hand once
-  the Postgres data has been trusted for a while:
-  `docker volume rm "$VOL"` (see `REDEPLOY.md` §1).
+  the Postgres data has been trusted for a while. That happens in a shell where
+  `$VOL` from §1 is long gone, so re-derive it:
+  `docker volume rm "$(basename ~/mangaBookmark | tr '[:upper:]' '[:lower:]')_bookmarks-data"`
+  (see `REDEPLOY.md` §1).
 - **Delete the generator and the working copies:** `rm -rf /tmp/cutover`. The
  timestamped export in `$BACKUP_DIR` is the copy that is kept.
 - **Take the first Postgres dump immediately** — `REDEPLOY.md` §1. Until that
@@ -11,7 +11,7 @@ ACME/cert resolver, and control a domain.
 - Docker + Docker Compose on the server.
 - A Traefik instance watching a Docker network (default name assumed: `proxy`).
 - DNS: an `A`/`AAAA` record for `bookmark-api.<yourdomain>` pointing at the server.
- The repo copied to the server, e.g. `/opt/bookmarkmanager/` (needs `backend/`,
+- The repo copied to the server, e.g. `~/mangaBookmark/` (needs `backend/`,
  `docker-compose.yml`, `docker-compose.prod.yml`, `.env.example`).

 Confirm the Traefik network exists (create if not):
@@ -25,7 +25,7 @@ docker network ls | grep proxy || docker network create proxy
 ## 1. Configure `.env`

 ```bash
-cd /opt/bookmarkmanager
+cd ~/mangaBookmark
 cp .env.example .env
 ```

@@ -33,6 +33,26 @@ Bromite userscript (isolated world, Shadow DOM UI, localStorage cache)
 | `DATABASE_URL` | *(required)* | Postgres connection URL, e.g. `postgres://bookmarks:…@postgres:5432/bookmarks?sslmode=disable`. Compose builds it from `POSTGRES_PASSWORD`. |
 | `PORT` | `8080` | Plain HTTP; TLS terminated by the proxy. |
 | `BROWSER_WS_URL` | `ws://172.28.0.10:9222` | Headless-shell CDP endpoint used to poll Kagane past its JS challenge. Must be an IP or `localhost` — Chrome's DevTools handler 500s any other Host header. |
+| `DISCORD_CLIENT_ID` | *(required)* | Discord application credentials for the browser sign-in (ADR-0002). |
+| `DISCORD_CLIENT_SECRET` | *(required)* | As above. Never logged, never echoed in an error. |
+| `DISCORD_GUILD_ID` | *(required)* | The one guild whose membership gates sign-in, checked at login only. |
+| `DISCORD_REDIRECT_URI` | *(required)* | Exact callback URL; Discord matches it verbatim against the registered redirect. |
+| `DISCORD_REQUIRED_ROLE` | empty | Role snowflake a member must additionally hold. Empty means guild membership alone suffices. |
+| `DISCORD_API_BASE` | `https://discord.com/api/v10` | Test seam — tests point it at a local stub so the real token exchange runs. |
+| `USERSCRIPT_PATH` | `/userscript/manga-bookmark.user.js` | Bindmounted file served at `/u/{token}/manga-bookmark.user.js`. |
+| `NOVEL_USERSCRIPT_PATH` | `/userscript/novel-bookmark.user.js` | Same, for the novel library. |
+| `LATEST_CHAPTER_POLL_ENABLED` | `1` | `0` turns the poller off entirely. |
+| `LATEST_CHAPTER_POLL_COOLDOWN` | `1h` | Rest between checks of one series; floor `15m`. |
+| `LATEST_CHAPTER_POLL_INTERVAL` | `10m` | How often the poller wakes. Cannot shorten a cooldown. |
+| `LATEST_CHAPTER_POLL_BATCH` | `14` | Series per wake. Keep `BATCH × STAGGER` under `INTERVAL`. |
+| `LATEST_CHAPTER_POLL_STAGGER` | `20s` | Delay between fetches in a batch — this is the outbound request rate. |
+
+Compose reads a few more from the same `.env` that the backend never sees:
+`POSTGRES_PASSWORD` (required — `DATABASE_URL` is built from it, and Postgres
+only applies it while `postgres-data` is empty), `BOOKMARK_API_HOST` and
+`BOOKMARK_WEB_HOST` (required by the prod override), and the optional
+`PROXY_NETWORK` / `TRAEFIK_ENTRYPOINT` / `TRAEFIK_CERTRESOLVER`. Full commentary
+is in `.env.example`; deployment order is `DEPLOY.md`.

 ### Endpoints

@@ -9,16 +9,16 @@ Whole thing is ~5 minutes, most of it waiting on `docker build`. Order matters:
 **back up before you pull.** A backup taken after a bad migration is a backup of
 the damage.

-Paths below assume the checkout is at `/opt/bookmarkmanager`; substitute your own. The
-one absolute rule about paths: **backups live in `../bookmarkmanager-backups/`**, a
-sibling of the project directory (`/opt/bookmarkmanager-backups`), never inside it. It
+Paths below assume the checkout is at `~/mangaBookmark`, which is where it lives
+on this deployment; substitute your own. The one absolute rule about paths:
+**backups live in a `-backups` sibling of the checkout**, never inside it. It
 sits outside the repo so `git pull`, `git clean -fd` and a bad `rm -rf` inside
 the checkout cannot take the backups with them.

 ```
-/opt/
-├── bookmarkmanager/            <- the checkout (this repo)
-└── bookmarkmanager-backups/    <- bookmarks-YYYYmmdd-HHMMSS.dump
+~/
+├── mangaBookmark/            <- the checkout (this repo)
+└── mangaBookmark-backups/    <- bookmarks-YYYYmmdd-HHMMSS.dump
 ```

 ---
@@ -26,7 +26,7 @@ the checkout cannot take the backups with them.
 ## 0. Preflight

 ```bash
-cd /opt/bookmarkmanager
+cd ~/mangaBookmark

 # Both -f flags, every time. The prod override is not standalone.
 COMPOSE="docker compose -f docker-compose.yml -f docker-compose.prod.yml"
@@ -44,9 +44,9 @@ dirty tree fails halfway and leaves you in a worse spot than either.
 Create the backup directory once, and make sure it is a sibling, not a child:

 ```bash
-mkdir -p ../bookmarkmanager-backups
-BACKUP_DIR="$(cd .. && pwd)/bookmarkmanager-backups"   # absolute — Docker needs it
-echo "$BACKUP_DIR"                             # -> /opt/bookmarkmanager-backups
+BACKUP_DIR="$(cd .. && pwd)/$(basename "$PWD")-backups"   # absolute — Docker needs it
+mkdir -p "$BACKUP_DIR"
+echo "$BACKUP_DIR"                        # -> /home/sulthan/mangaBookmark-backups
 ```

 ---
@@ -131,8 +131,11 @@ container stopped the shutdown checkpoint has already flushed everything and a
 plain archive of the volume is consistent.

 ```bash
-VOL=$(docker volume ls --filter name=postgres-data -q | head -1)
-echo "$VOL"                          # -> bookmarkmanager_postgres-data
+# Derived exactly, not with a `--filter name=` substring match plus `head -1`:
+# that quietly picks the first of however many volumes happen to contain the
+# string, and archiving the wrong data directory is not a visible failure.
+VOL="$(basename "$PWD" | tr '[:upper:]' '[:lower:]')_postgres-data"
+docker volume inspect "$VOL" >/dev/null && echo "$VOL"   # -> mangabookmark_postgres-data

 $COMPOSE stop
 docker run --rm -v "$VOL":/from:ro -v "$BACKUP_DIR":/to alpine \
@@ -165,10 +168,10 @@ down -v` from taking it with the rest of the stack. It is not the live database
 and nothing reads it — the one-way move out of it is `CUTOVER.md`. Once the
 Postgres data has been trusted for a while, remove it by hand — nothing else will.
 Its full name is `<compose project>_bookmarks-data`, and the project name is the
-lowercased directory name of the checkout, so ask Docker rather than typing it:
+lowercased directory name of the checkout:

 ```bash
-docker volume rm "$(docker volume ls -q --filter name=_bookmarks-data)"
+docker volume rm "$(basename "$PWD" | tr '[:upper:]' '[:lower:]')_bookmarks-data"
 ```

 ---