diff options
Diffstat (limited to 'docs/CONFIGURATION.txt')
| -rw-r--r-- | docs/CONFIGURATION.txt | 156 |
1 files changed, 74 insertions, 82 deletions
diff --git a/docs/CONFIGURATION.txt b/docs/CONFIGURATION.txt index fc18c41..f0f8457 100644 --- a/docs/CONFIGURATION.txt +++ b/docs/CONFIGURATION.txt @@ -15,137 +15,129 @@ along with this program. If not, see <https://www.gnu.org/licenses/>. CENTRAL CONFIGURATION - Each installation has one root .env for deployment settings and secrets. - The published .env.example documents every supported setting with public - defaults, private placeholders, and comments. Hostnames are public information; - this arrangement centralizes configuration, not secrecy or access control. - Public values remain visible in generated pages, DNS, certificates, and URLs. - - Existing installations keep their configured secrets and settings. Missing - public defaults are appended to the same .env by cargo stack config, service - initialization, or chat initialization. No second environment file is created. - The example is also the shared Rust configuration library's default source, - so missing public settings remain compatible with older exports. + One root .env holds each installation's deployment settings and secrets. + Public .env.example documents every supported key, public default, private + placeholder, and comment. Hostnames remain public in generated pages, DNS, + certificates, and URLs. Centralization is not secrecy or access control. + + cargo stack config, service initialization, and chat initialization preserve + existing settings/secrets and append missing public defaults to the same .env. + No second environment file. The shared Rust configuration library also reads + defaults from .env.example, keeping older exports compatible. PUBLIC SETTINGS BASE_DOMAIN - Root web/WKD domain. www aliases are derived from each configured host. + Root web/WKD domain. Derive www aliases from each configured host. SITE_HOST, GIT_HOST, SEARCH_HOST, WKD_HOST, CHAT_HOST - 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. + Fully qualified DNS names; no scheme, path, or port. Set production + HTTPS routes and canonical www redirects. CHAT_HOST also selects the + exact trusted external chat origin. CHAT_LOCAL_HOST - Dedicated development gateway hostname ending in .localhost. Default: + 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. + Production publish address. Default :: serves IPv4/IPv6. Use 127.0.0.1 + for isolated staging. Development always binds loopback. HTTP_PORT, HTTPS_PORT - Production Caddy listener and Podman published ports. HTTPS also publishes - UDP for HTTP/3. Defaults are 80 and 443. Generated HTTPS links include a - nonstandard HTTPS port when configured. Ordinary public certificate - validation still needs the CA's standard external validation ports or an - appropriate alternative certificate/routing arrangement. Setting ports - alone does not configure DNS, firewall rules, or external port forwarding. + Caddy listeners and Podman published ports; defaults 80/443. HTTPS also + publishes UDP for HTTP/3. Generated links include nonstandard HTTPS ports. + Public certificate validation still needs standard external CA validation + ports or alternative certificate/routing arrangements. Port settings do + not configure DNS, firewall rules, or external forwarding. LOCAL_HTTP_PORT - Local Caddy HTTP port on 127.0.0.1. HTTPS host port is this value plus one. - Local Caddy still listens on container ports 80/443. --port overrides the - local port for that invocation. Existing installation/project names and - image state remain in var/state.json; an explicit .env local port takes - precedence over the previously saved port. + Local HTTP on 127.0.0.1; host HTTPS port is this value plus one. Caddy + still listens on container ports 80/443. --port overrides one invocation. + var/state.json retains installation/project names and image state. + An explicit .env local port overrides the saved port. 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. + Proxy targets, e.g. cgit:8080, searxng:8080, chat:8080. Not bind settings. + Bundled internal 8080 listeners and health checks remain image contracts. + A changed target needs an actual service at that host/port. CHAT_BIND, CHAT_ORIGIN 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. + 127.0.0.1:9080 and http://127.0.0.1:9080. Require loopback and an exact + HTTP origin match. --bind overrides CHAT_BIND. Containers bind privately + to 0.0.0.0:8080; trusted origin comes from CHAT_HOST/HTTPS_PORT or + CHAT_LOCAL_HOST/LOCAL_HTTP_PORT. Identity files pin their origin. + Editing these settings neither migrates encrypted identities nor grants + access on another origin. BACKUP_RECIPIENT, BACKUP_PUBLIC_KEY - Public OpenPGP fingerprint and project-relative public key path used for - encrypted exports. --recipient and --key override them. The secret GnuPG - key and revocation certificate remain outside the project. + Public OpenPGP fingerprint and project-relative public key path for + encrypted exports. --recipient/--key override them. Keep the secret + GnuPG key and revocation certificate outside the project. PRIVATE SETTINGS SEARXNG_SECRET - Generated on first stack initialization. Existing values are preserved. + Generated at first stack initialization; existing values preserved. CHAT_SETUP_TOKEN - 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. + Generated by chat initialization or first startup. Authorizes only + first owner registration, including after an explicit backend reset. + Cannot recover a lost owner private key. RENDER AND APPLY - Edit .env locally. Never commit or publish it. Inspect the commented example - for exact keys. Hostnames, ports, socket addresses, fingerprints, and paths - are validated before use. Diagnostic formatting never dumps the config map. - Invalid environment-file syntax is reported without echoing its raw contents. + Edit .env locally; never commit or publish it. See .env.example for exact + keys. Validate hostnames, ports, sockets, fingerprints, and paths before use. + Diagnostics never dump the config map or echo invalid .env contents. Render public deployment files without starting services: cargo stack config cargo stack config --production - Outputs are var/local/ or var/production/: + Output under var/local/ or var/production/: Caddyfile cgitrc web/ - infra/Caddyfile, infra/Caddyfile.local, infra/containers/cgit/cgitrc, and the - first-party website HTML are templates using {{PUBLIC_KEY}} placeholders. - 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 http://CHAT_LOCAL_HOST:LOCAL_HTTP_PORT for chat. + Templates use {{PUBLIC_KEY}} placeholders: infra/Caddyfile, + infra/Caddyfile.local, infra/containers/cgit/cgitrc, first-party website HTML. + Never run Caddy on unrendered templates. Podman mounts generated files. + Public host/origin changes reach routes, www redirects, website links, cgit + clone prefixes, and chat navigation. Local rendering uses /git, /search, + and http://CHAT_LOCAL_HOST:LOCAL_HTTP_PORT for chat. - To apply changes to the existing services: + Apply to existing local services: cargo stack up --local - Production uses its prebuilt management command and images: + Production uses prebuilt management command/images: ./bin/stack up --production - Rendered website files can be read by an already running file server, while - listeners, container environment, and loaded Caddy configuration require the - service update above. Restart the local chat server with cargo stack chat to - load its new bind, origin, or public navigation settings. Reopen your identity - file afterward, as with any chat restart. + Running file servers can read rendered website updates. Listener, container + environment, and loaded Caddy changes need the service update above. + Restart direct local chat with cargo stack chat for new bind/origin/navigation + settings. Reopen your identity file afterward, as after any chat restart. 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. 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 - remain ignored by Git. Source templates, the commented example, validated - defaults, and this configuration implementation are public. Full encrypted - backups include the single .env; source-only releases do not include it. - - Personal content and attribution remain source content: copyright headers, - author names, canonical contact information, public key material/WKD hashes, - project repository metadata, and GNU license links. Changing a deployment - hostname does not create a new email identity or regenerate WKD keys. - Image digests, source hashes, and fixed crypto/protocol/resource bounds remain - reviewed reproducible code/configuration rather than private deployment knobs. + stack-config substitutes only explicitly allowlisted public values. + {{CHAT_SETUP_TOKEN}} and other private/unknown placeholders fail instead of + exposing values. Public pages/proxy config never receive a full environment + dump. Chat receives the public allowlist plus CHAT_SETUP_TOKEN; other + containers receive only declared secrets. Caddy needs rendered public config, + not .env or private tokens. + + Git ignores .env, runtime files, local renders, exports, and tool caches. + Source templates, commented example, validated defaults, and configuration + implementation remain public. Full encrypted backups include the single + .env; source-only releases exclude it. + + Personal content stays in source: copyright, author names, canonical contact, + public keys/WKD hashes, repository metadata, GNU license links. Changing a + hostname creates no new email identity and regenerates no WKD keys. + Image digests, source hashes, fixed crypto/protocol/resource bounds remain + reviewed reproducible code/config, not private deployment knobs. |