Move the browser off the VPS to its own unit (#46) (#52)

Closes #46 once deployed.

The headless browser leaves the API stack and becomes its own compose unit
(`chrome/docker-compose.yml`) intended for the home machine, reached over the
tailnet. No fallback sidecar is left on the VPS.

The backend needs no code change — `BROWSER_WS_URL` was already the only
coupling. Its default is now empty rather than a pinned Docker IP, so an
unconfigured or unreachable browser degrades exactly as it always has: plain-TLS
libraries unaffected, kagane/novelfull logged and skipped, stored covers still
served.

### What shipped

- `chrome/docker-compose.yml` + `chrome/.env.example` — the browser unit, with
  the CDP port bound to `${BROWSER_BIND_ADDR}` (no default) and the resource
  limits from the epic: 512 MiB / 1 GiB memory+swap, `oom_score_adj 800`,
  halved CPU weight, shm 1 GiB -> 128 MiB.
- API stack drops the service, its `depends_on` and the `browser` network.
- `bookmark-api` gains the `default` network. Dropping `browser` had left it on
  `db` alone, which is `internal: true` — no published port and, worse, no
  egress for the poller at all. Caught by actually bringing the stack up.
- ADR-0006 for the topology; `DEPLOY.md` §7 for first-time setup of the browser
  machine; `REDEPLOY.md` §8 for its independent update cadence; architecture
  diagrams, config tables and troubleshooting rows across README/AGENTS/env.

### Verified locally

- Browser unit builds and runs: Chrome 151, UA carries no `HeadlessChrome`,
  all limits applied as declared.
- **Live smoke passes through the new unit**: `TestSmokeKaganeImage` fetched
  56710 bytes of `image/webp`, `TestSmokeKaganeGet` got a 200 with a real
  chapter list. The challenge cleared under the reduced 128 MiB shm.
- Bind isolation proven: refused on the host's non-loopback address, accepted
  on the configured one.
- 321 MiB peak of the 512 MiB cap after a full solve; 0 restarts, no OOM kill.
- API stack comes up clean, `/healthz` 200; egress confirmed present on
  `default` and absent on `db`.
- `go test ./...`, `go vet`, `gofmt` clean.

### Left to the operator

Provisioning the home machine, the Tailscale ACL, setting `BROWSER_WS_URL` in
production, and observing acceptance criteria 5-7 (covers with the machine off,
several days of zero OOM/restarts, VPS memory improvement). `DEPLOY.md` §7 now
carries the before/after `free -m` reading those need.

Reviewed-on: #52
Co-authored-by: Sulthan Zaki <sultankiki05@gmail.com>
Co-committed-by: Sulthan Zaki <sultankiki05@gmail.com>

backend/AGENTS.md

@@ -128,10 +128,13 @@ Guidance for OpenCode (and Claude Code) working under `backend/`. See root `AGEN
   `/userscript/novel-bookmark.user.js`, both supplied by bindmount; the
   `__API_TOKEN__` placeholder inside them is substituted with the requesting
   Reader's credential at serve time).
-  `BROWSER_WS_URL` (CDP endpoint of the `chrome/` sidecar, used by the poller
-  for kagane and novelfull *and* by the web UI's kagane cover proxy; unset
-  disables browser polling and serves 404 from the proxy, leaving those sites
-  to the userscript alone).
+  `BROWSER_WS_URL` (CDP endpoint of the browser, which runs on a **separate
+  machine** and is reached over the tailnet — ADR-0006, `chrome/docker-compose.yml`.
+  Used by the poller for kagane and novelfull *and* by the web UI's kagane
+  cover proxy; unset — the default — disables browser polling and serves 404
+  for covers not already stored, leaving those sites to the userscript alone.
+  Must be a tailnet IP, never a hostname: Chrome's DevTools handler 500s
+  `/json/version` for any Host that isn't an IP or `localhost`).
 - **kagane covers are proxied, not hot-linked:** kagane serves cover images
   behind the same challenge as its pages and with
   `cross-origin-resource-policy: same-origin`, so no `<img>` on the web UI's

backend/internal/latest/browser.go

@@ -53,19 +53,22 @@ var kaganeImageIDRe = regexp.MustCompile(`^[0-9a-f-]{36}$`)
 type BrowserFetcher struct {
 	allocCtx context.Context
 	cancel   context.CancelFunc
-	// One page at a time: caps the sidecar's memory and keeps series from
-	// sharing page state.
+	// One page at a time: caps the browser's memory — it runs under a hard
+	// cgroup cap on a shared machine — and keeps series from sharing page state.
 	mu sync.Mutex
 }
 
 var _ Fetcher = (*BrowserFetcher)(nil)
 
-// NewBrowserFetcher connects to a headless-shell over CDP. wsURL must name the
-// sidecar by IP, e.g. ws://172.28.0.10:9222 — not by Docker DNS name. Chrome's
-// DevTools HTTP handler 500s any /json/version request whose Host header
-// isn't an IP or "localhost" (confirmed 2026-08-03 against
-// chromedp/headless-shell:stable), so the compose network pins the sidecar's
-// address for this to resolve at all.
+// NewBrowserFetcher connects to a Chrome over CDP. The browser is not a
+// sidecar: it runs on a separate machine and is reached over the tailnet
+// (ADR-0006), so wsURL is that machine's tailnet address, e.g.
+// ws://100.64.0.5:9222.
+//
+// It must be an IP, never a hostname — not MagicDNS, not a Docker service
+// name. Chrome's DevTools HTTP handler 500s any /json/version request whose
+// Host header isn't an IP or "localhost" (confirmed 2026-08-03), so a name
+// fails at discovery and surfaces as a dead site rather than a bad URL.
 //
 // Do not add chromedp.NoModifyURL here: that option skips the /json/version
 // discovery request entirely and dials wsURL as if it were already the full
@@ -73,8 +76,10 @@ var _ Fetcher = (*BrowserFetcher)(nil)
 // /devtools/browser/<uuid>, a path chosen fresh at every Chrome start — dialing
 // the bare host:port 404s. The default (discovery) path works precisely
 // because Chrome's /json/version response echoes back the Host header of the
-// discovery request in webSocketDebuggerUrl, so as long as wsURL is a
-// container-reachable IP, the URL chromedp gets back already points at it.
+// discovery request in webSocketDebuggerUrl, so as long as wsURL is an IP this
+// process can reach, the URL chromedp gets back already points at it. That is
+// also why a Chrome restarted behind a stable endpoint needs no reconnect
+// here: the fresh UUID arrives with the next discovery.
 func NewBrowserFetcher(wsURL string) (*BrowserFetcher, error) {
 	if wsURL == "" {
 		return nil, fmt.Errorf("empty browser websocket url")

backend/internal/latest/smoke_image_test.go

@@ -9,11 +9,14 @@ import (
 )
 
 // TestSmokeKaganeImage is the live proof that the cover proxy's fetch actually
-// clears Cloudflare and returns image bytes. It needs a real headless Chrome
+// clears Cloudflare and returns image bytes. It needs the real browser unit
 // with outbound network, so it runs only when SMOKE_BROWSER_WS_URL is set:
 //
-//	docker run --rm --shm-size=1gb -p 19222:9222 chromedp/headless-shell:stable
-//	SMOKE_BROWSER_WS_URL=ws://127.0.0.1:19222 go test -run TestSmokeKaganeImage ./internal/latest
+//	cd chrome && BROWSER_BIND_ADDR=127.0.0.1 docker compose up -d --build
+//	SMOKE_BROWSER_WS_URL=ws://127.0.0.1:9222 go test -run TestSmokeKaganeImage ./internal/latest
+//
+// Not chromedp/headless-shell: its challenge never clears (see chrome/Dockerfile),
+// so a red run there proves nothing about kagane.
 func TestSmokeKaganeImage(t *testing.T) {
 	ws := os.Getenv("SMOKE_BROWSER_WS_URL")
 	if ws == "" {