diff options
Diffstat (limited to 'docs/CONFIGURATION.txt')
| -rw-r--r-- | docs/CONFIGURATION.txt | 35 |
1 files changed, 22 insertions, 13 deletions
diff --git a/docs/CONFIGURATION.txt b/docs/CONFIGURATION.txt index 9660e20..fc18c41 100644 --- a/docs/CONFIGURATION.txt +++ b/docs/CONFIGURATION.txt @@ -33,10 +33,17 @@ PUBLIC SETTINGS Root web/WKD domain. www aliases are derived from each configured host. SITE_HOST, GIT_HOST, SEARCH_HOST, WKD_HOST, CHAT_HOST - Fully qualified DNS names without schemes, paths, or ports. The first - four configure production Caddy routing. CHAT_HOST supplies the intended - public chat link; production chat routing remains unimplemented on this - experimental feature branch. + Fully qualified DNS names without schemes, paths, or ports. These + configure production HTTPS routes and their canonical www redirects. + CHAT_HOST also selects the exact trusted external chat origin. + + CHAT_LOCAL_HOST + Dedicated development gateway hostname ending in .localhost. Default: + chat.localhost. Browser identity files bind to this origin and local port. + + WEB_BIND + Production host publish address. Default :: serves IPv4 and IPv6. Use + 127.0.0.1 for isolated staging; development mode always uses loopback. HTTP_PORT, HTTPS_PORT Production Caddy listener and Podman published ports. HTTPS also publishes @@ -53,16 +60,18 @@ PUBLIC SETTINGS image state remain in var/state.json; an explicit .env local port takes precedence over the previously saved port. - CGIT_UPSTREAM, SEARXNG_UPSTREAM - Proxy connection targets such as cgit:8080 and searxng:8080. These are + CGIT_UPSTREAM, SEARXNG_UPSTREAM, CHAT_UPSTREAM + Proxy connection targets such as cgit:8080, searxng:8080, and chat:8080. These are addresses, not upstream bind settings. The bundled images' internal 8080 listeners and health checks remain image contracts. Changing a target to another host/port requires an actual service at that address. CHAT_BIND, CHAT_ORIGIN - Chat socket and exact browser origin. Default: 127.0.0.1:9080 and - http://127.0.0.1:9080. The experimental server requires loopback and an - exact HTTP origin match. --bind overrides CHAT_BIND for testing. + Direct development socket and exact browser origin. Defaults: + 127.0.0.1:9080 and http://127.0.0.1:9080. Direct development requires + loopback and an exact HTTP origin match. --bind overrides CHAT_BIND. + The container binds privately to 0.0.0.0:8080; its trusted origin comes + from CHAT_HOST/HTTPS_PORT or CHAT_LOCAL_HOST/LOCAL_HTTP_PORT instead. Identity files pin their origin; editing these values does not migrate encrypted identities or grant access on another origin. @@ -77,7 +86,7 @@ PRIVATE SETTINGS Generated on first stack initialization. Existing values are preserved. CHAT_SETUP_TOKEN - Generated by cargo stack chat --init. Used only to authorize first owner + Generated by chat initialization or first stack startup. Used only to authorize first owner registration, including a fresh registration after an explicit backend reset. It cannot recover a lost owner private key. @@ -104,7 +113,7 @@ RENDER AND APPLY Do not run Caddy directly on an unrendered template. Podman mounts the generated files. Public host/origin changes reach Caddy routes, www redirects, website links, the cgit clone prefix, and the chat page's navigation. Local rendering - uses /git and /search paths and the configured local chat origin. + uses /git and /search paths and http://CHAT_LOCAL_HOST:LOCAL_HTTP_PORT for chat. To apply changes to the existing services: @@ -125,8 +134,8 @@ PUBLICATION AND LIMITS The shared stack-config crate uses an explicit public allowlist for template substitution. A {{CHAT_SETUP_TOKEN}} or other private/unknown placeholder causes an error rather than publishing its value. Generated public pages and - proxy configuration never receive a full environment dump. Each container - still receives only the environment keys listed for that service; Caddy uses + proxy configuration never receive a full environment dump. Chat receives the public configuration allowlist plus CHAT_SETUP_TOKEN; + other containers receive only their declared service secrets. Caddy uses rendered public configuration and does not need the .env or private tokens. The root .env, runtime files, local render outputs, exports, and tool caches |