Configuration

Chinaski is configured in two layers: a handful of environment variables set per instance (the deployment-level knobs) and the Settings area inside the admin interface (site-level configuration, stored in the database). This page explains the six core environment variables and where every other customization belongs.

The six core environment variables

Per instance, these live in a permission-locked env file (/etc/chinaski<instance>/env, created at install). Offline/hypnotoad deployments export them directly.

Variable	What it does	What to know
CHINASKI_SECRET	Signs admin sessions and keys the encryption for stored credentials	Required. The server refuses to start without it. Generated automatically at install, printed once, saved in the env file. Unique per instance; never change it casually (see Secrets)
CHINASKI_DB	Where the SQLite database file lives	Normally derived automatically from the instance name by the systemd unit, leave unset
CHINASKI_OUTPUT	Where static builds are written	Same story: derived per instance by the unit
LISTEN_URL	The address the server binds	Bind to loopback (http://127.0.0.1:3001 pattern): the proxy faces the internet, the CMS does not. Binding to a public interface defeats the server’s IP-spoof protection for rate limiting and lockouts
CHINASKI_WORKERS	Number of server workers	Default 2. Raise to 4 on 2+ GB hosts with multiple concurrent editors
MOJO_MODE	Runtime mode	Production deployments set production (the systemd unit does this for you)

Note for the two listen variables: CHINASKI_LISTEN is the value the built-in (offline/hypnotoad) server reads directly, default http://127.0.0.1:8080. LISTEN_URL is what the systemd unit passes to the daemon under production. In a standard production deploy, set LISTEN_URL; in offline mode, set CHINASKI_LISTEN (or leave it to the bundled hypnotoad config).

The settings you change from the admin UI

Everything else about how the site behaves is Settings, stored in the database (survives rebuilds, included in backups):

• Site identity: name, tagline, logo, favicon set, language list, URL mode
• SEO fields, sitemap defaults, redirects, permalink prefixes
• Email (SMTP), security/cookie texts, bot-check keys
• Build webhooks, self-registration, password-expiry, backups schedule/retention
• Design tokens, PWA toggles, Google Analytics/GTM, and so on

If what you’re changing has a screen in Settings, change it there; env vars are deployment-level, not site-level.

Environment variables beyond the core six

• CHINASKI_AIRGAP=1: makes the installation prove it never calls out: build and form webhooks off, bot-check verification off, the check widget hidden. Set before starting on isolated hosts.
• CHINASKI_TRUSTED_PROXIES: comma-separated IPs or IPv4 ranges allowed to forward visitor IPs (only needed if your proxy doesn’t reach the CMS from loopback, Docker-style setups).
• CHINASKI_ALLOW_BUILD_FAIL=1: used in front of the deploy script to push an emergency code-only fix even when a build is failing.
• A few others exist in the code for update-verification, custom docs paths, and release keys; they’re recognized but not covered as documented settings in this release; treat anything not listed here as internal.

Where changes take effect

• Env-file changes need a restart (systemctl restart chinaski@<instance>); they’re read once at startup.
• Settings changes take effect immediately for the CMS, and reach the published site on the next build.
• The master secret affects both signs-in (all existing sessions die on rotation) and stored credentials, re-save each integration credential after a rotation (see Secrets).

The short version

Six env vars run the process (SECRET required; DB/OUTPUT auto-derived; LISTEN_URL loopback-only; MODE; WORKERS); everything else a site owner wants lives in Settings, and anything you find yourself reaching for an env var for beyond these six is either an operator flag from the CLI/Server page or something the docs site covers where it belongs (airgap, proxies, deploy scripts).