Centralize deployment settings in the root environment file

Document public domains, ports, upstreams, chat binding, and backup defaults alongside private settings. Validate shared configuration and render Caddy, cgit, and website links from an explicit public allowlist while preserving one installation environment file.

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.