diff options
Diffstat (limited to 'docs/CONFIGURATION.txt')
| -rw-r--r-- | docs/CONFIGURATION.txt | 142 |
1 files changed, 142 insertions, 0 deletions
diff --git a/docs/CONFIGURATION.txt b/docs/CONFIGURATION.txt new file mode 100644 index 0000000..9660e20 --- /dev/null +++ b/docs/CONFIGURATION.txt @@ -0,0 +1,142 @@ +Copyright (C) 2026 Doan Luu Duc Tai <doan@luuduct.ai> + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU Affero General Public License as +published by the Free Software Foundation, either version 3 of the +License, or (at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU Affero General Public License for more details. + +You should have received a copy of the GNU Affero General Public License +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. + +PUBLIC SETTINGS + + BASE_DOMAIN + 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. + + 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. + + 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. + + CGIT_UPSTREAM, SEARXNG_UPSTREAM + Proxy connection targets such as cgit:8080 and searxng: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. + Identity files pin their origin; editing these values does not migrate + encrypted identities or grant 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. + +PRIVATE SETTINGS + + SEARXNG_SECRET + Generated on first stack initialization. Existing values are preserved. + + CHAT_SETUP_TOKEN + Generated by cargo stack chat --init. Used only to authorize first owner + registration, including a fresh registration after an explicit backend + reset. It 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. + + Render public deployment files without starting services: + + cargo stack config + cargo stack config --production + + Outputs are 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 the configured local chat origin. + + To apply changes to the existing services: + + cargo stack up --local + + Production uses its prebuilt management command and 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. + +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 + 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. |