stash

deploy/prod/README.md

@@ -3,7 +3,10 @@
 `playbook.yml` automates installing docker.io and nginx (plus certbot, and
 obtaining/renewing a TLS certificate with it, on hosts that manage their own
 — see `behind_tls_proxy` below), building the backend, frontend and wiki
-images, exporting the frontend and wiki static builds for nginx to serve,
+images, exporting the frontend/wiki static builds and the backend's
+`collectstatic` output for nginx to serve directly (nginx also serves
+user-uploaded files directly, via an X-Accel-Redirect Django issues after its
+own permission check — see `location /redirect_media/` in `playbook.yml`),
 writing the small `/local/domains` and `/local/dns` fixture files the
 frontend fetches directly (registration domain list and DoH resolver
 preference — see `toolshed_register_domains`/`toolshed_doh_resolvers` in
@@ -51,8 +54,11 @@ toolshed:
   in `user@yourtoolshed.tld`) — see [DNS](#3-dns) for how those two relate.
 - `toolshed_handle_domain` — the **handle domain**, only needed when it's
   different from `toolshed_domain`. Omit it when the two are the same (it
-  then defaults to `toolshed_domain`). Set so nginx/Django accept requests
-  for either domain, whichever ends up as the `Host` header.
+  then defaults to `toolshed_domain`). It doesn't affect nginx/Django at all
+  (they only ever accept `toolshed_domain` as the `Host` header) — it's used
+  solely to populate the `/local/domains` registration fixture (see
+  `toolshed_register_domains` in `playbook.yml`); publishing the SRV record is a
+  separate, manual DNS step either way.
 - `toolshed_repo_url` — the git remote the playbook checks out and builds
   from. Required, no default.
 - `toolshed_version` — the branch, tag or commit to check out and build.
@@ -94,10 +100,12 @@ There are two distinct domains at play here, and it's easy to conflate them:
   `user@yourtoolshed.tld`. Toolshed usernames don't encode a server address
   directly; the frontend resolves the handle domain to a server via an SRV
   record, `_toolshed-server._tcp.<handle domain>.` (see
-  `frontend/src/store.js`, `lookupServer`). What's in `toolshed_handle_domain`
-  (see [Per-deployment configuration](#2-per-deployment-configuration)) only
-  makes nginx/Django accept it as a `Host` header — publishing the actual SRV
-  record is still a separate, manual DNS step, covered below.
+  `frontend/src/store.js`, `lookupServer`), which always points at the web
+  domain — nginx/Django never see the handle domain as a `Host` header.
+  `toolshed_handle_domain` (see [Per-deployment
+  configuration](#2-per-deployment-configuration)) only feeds the
+  `/local/domains` registration fixture; publishing the actual SRV record is
+  still a separate, manual DNS step, covered below.
 
 The SRV lookup happens for every login, not just federation with other
 servers, so **every** deployment needs it published for its own handle