diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/CHAT-APPLICATION.txt | 2 | ||||
| -rw-r--r-- | docs/CONFIGURATION.txt | 142 | ||||
| -rw-r--r-- | docs/OPERATIONS.txt | 4 | ||||
| -rw-r--r-- | docs/POLICY.txt | 9 |
4 files changed, 153 insertions, 4 deletions
diff --git a/docs/CHAT-APPLICATION.txt b/docs/CHAT-APPLICATION.txt index 7b4dc40..7e58051 100644 --- a/docs/CHAT-APPLICATION.txt +++ b/docs/CHAT-APPLICATION.txt @@ -67,6 +67,8 @@ LOCAL PREREQUISITES AND COMMANDS .env, creating it privately if necessary. It refuses to overwrite an existing setup token. The root .env.example lists both settings. Never commit .env. Existing SearXNG settings stay in the same file. No crate has its own .env. + CHAT_BIND and public navigation now use the shared root configuration loader; + see CONFIGURATION.txt for the documented deployment keys. For subsequent Rust-only edits, sh infra/chat/build-browser.sh reuses the previously built, hash-verified OpenSSL/SDK inputs. Rebuild OpenSSL itself 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. diff --git a/docs/OPERATIONS.txt b/docs/OPERATIONS.txt index 826c4cf..2cf4693 100644 --- a/docs/OPERATIONS.txt +++ b/docs/OPERATIONS.txt @@ -218,7 +218,9 @@ SET UP A NEW PRODUCTION HOST Point public A records to the new IPv4 address, and AAAA records only to a working new IPv6 address. Remove stale AAAA records. Public hostnames are - listed in infra/Caddyfile. Update canonical hosts there if changing domains. + configured in the root .env. Edit those values and reapply the service + configuration; infra/Caddyfile is now a public rendering template. + See CONFIGURATION.txt for all keys and the render-only commands. Keep the www aliases and openpgpkey names pointing to the canonical hosts. Start production: diff --git a/docs/POLICY.txt b/docs/POLICY.txt index 4c8d0bd..f662dd4 100644 --- a/docs/POLICY.txt +++ b/docs/POLICY.txt @@ -30,10 +30,13 @@ PROJECT CONVENTIONS documentation. The generated HTML license page is an explicit exception. Rust documentation attributes provide crate metadata without comments. - Keep configured secrets only in the root .env. Never commit .env or var/. + Keep deployment overrides and configured secrets in the single root .env. + Never commit .env or var/. Only the root .env.example is published; environment variants and nested - examples are ignored. .env.example lists required keys with placeholders. Public hostnames, - public GPG keys, paths, configuration, and source belong in Git. + examples are ignored. The commented .env.example publishes supported public + defaults and private placeholders. Public GPG keys, paths, templates, shared + configuration logic, and source belong in Git. Actual public hostnames remain + visible in rendered pages; .env centralization is not an access boundary. TLS account/certificate private keys, databases, and other generated private state are persistent data in var/data, not .env configuration. The GPG secret key and revocation certificate remain outside this project. |