Built with Chinaski

Environment Variables

Chinaski is configured through a handful of environment variables: the database location, the static output directory, the security secret, and a few optional overrides. The installer writes them for you; this page is the complete reference for when you need to change them by hand.

Where to set them

  • Single-instance installs: /etc/chinaski<N>/env (the file the chinaski@<N> systemd unit loads). Keep the file mode 0600.
  • The MCP server: /etc/chinaski<N>/mcp-env, read by chinaski-mcp@<N>.
  • Backup script and deploy script: in the environment at invocation time.
  • The created file ships with CHINASKI_SECRET set and CHINASKI_AIRGAP=1 active.

Required

Variable What it does Default
CHINASKI_SECRET Session signing key, and the key used to encrypt stored secrets (SMTP password) in the database. The CMS refuses to start without it. The installer generates one with openssl rand -hex 32. none
CHINASKI_DB Path to the SQLite database file. <app root>/chinaski.db
CHINASKI_OUTPUT Directory the static builder writes to. <app root>/output
LISTEN_URL Address the CMS daemon binds to (used by the systemd unit). Must be loopback (e.g. http://127.0.0.1:3001) in production. In combination with CHINASKI_SECRET, this lives in /etc/chinaski<N>/env. none

Changing CHINASKI_SECRET invalidates admin sessions (everyone is logged out) and makes previously encrypted stored values (such as the SMTP password) undecryptable; re-save those settings after rotating the key.

Bind LISTEN_URL to loopback, not a public interface. The CMS only trusts X-Forwarded-For from loopback peers; a public bind would let any client spoof headers that feed IP-based rate limiting and login lockouts.

Listening

  • CHINASKI_LISTEN: listen address when running under hypnotoad. Default http://127.0.0.1:8080.
  • CHINASKI_WORKERS: hypnotoad worker count. Default 2.
  • MOJO_MODE: standard Mojolicious mode. Production units set production.

The current values of CHINASKI_DB, CHINASKI_OUTPUT, CHINASKI_URL_BASE, CHINASKI_LISTEN, and whether CHINASKI_SECRET is set are visible on the admin settings page.

Air-gap mode (CHINASKI_AIRGAP=1)

Disables every outbound call and external integration in one switch. With air-gap mode on:

  • Build, form, post, and publish webhooks are never delivered.
  • rsync and S3 deployment do not run, and webhook retries stop.
  • Cloudflare Turnstile is skipped entirely: verification auto-passes and the widget is removed from the login and form pages, regardless of keys stored in settings.
  • Admin email notifications are skipped.
  • The version-update manifest check is not performed.
  • The static builder strips external analytics (GA4/GTM) and strips snippet code that references external URLs, so no public page pulls anything from a CDN.

The installer enables this by default.

Static build

  • CHINASKI_INCREMENTAL=1: requests an incremental build. The builder may still choose a full build if it decides one is required.
  • CHINASKI_FORCE_FULL=1: forces a complete rebuild (used by bin/force-full-build.pl and the admin rebuild control).
  • CHINASKI_FORCE_PROMOTE=1: promotes the build even when the quality guard would hold it back because page counts or other metrics dropped.
  • CHINASKI_JOBS: build parallelism. Must be a plain number; overrides the build_jobs setting; defaults to the CPU count; clamped to 1..16.
  • CHINASKI_BLOCK_TEMPLATES: directory of block templates. Default builder/block_templates in the repo.
  • CHINASKI_MANIFEST_OPTIONAL=1: a failure to produce the signed build manifest normally aborts the build; setting this makes it a warning instead. Leave off in production: a “green” build without a usable signed manifest is worse than a failed build.

Signing, keys, and updates

  • CHINASKI_PRIVATE: directory holding the signed build manifest (build-manifest.json and its .sig). Default <repo root>/private.
  • CHINASKI_KEYS: directory holding the Ed25519 manifest signing keypair. Default <repo root>/keys.
  • CHINASKI_URL_BASE: overrides the chinaski_url_base site setting for built URLs and the sitemap.
  • CHINASKI_CMS_URL: overrides the cms_base_url setting.
  • CHINASKI_UPDATE_MANIFEST_URL: if set, the admin dashboard checks this manifest URL for newer releases (skipped in air-gap mode). Fetches with short 3/5-second timeouts.
  • CHINASKI_RELEASE_PUBKEY: alternate release-verification public key file; default keys/chinaski_release.pub in the app directory.

Runtime and operations

  • CHINASKI_TRUSTED_PROXIES: comma-separated list of proxy IPs or IPv4 CIDR ranges whose X-Forwarded-For headers are trusted. Loopback is always trusted; extra entries matter when your reverse proxy is otherwise visible to the app in a container/bridge network. Default: loopback only.
  • CHINASKI_SMTP_INSECURE_NOVERIFY=1: disables TLS certificate verification for outbound SMTP. Only for testing or deliberately insecure mail setups.
  • CHINASKI_SKIP_PERF_INDEXES=1: skips applying the automatic performance indexes; for migration tooling, not normal use.
  • CHINASKI_DOCS_DIR: documents directory. Default: documents next to the database file.
  • CHINASKI_MEDIA_DIR: media directory (used by the backup script and the automatic purge of trashed media files). Default public/media in the app tree (/var/www/chinaski<N>/public/media on systemd installs).
  • CHINASKI_ADMIN_PASSWORD: password for non-interactive bin/chinaski-setup.pl runs (alternative to --password).

Webhooks

  • WEBHOOK_MAX_CONCURRENT: maximum simultaneous outbound webhook requests. Default 8.

MCP server

chinaski-mcp requires CHINASKI_API_URL (CMS base URL) and CHINASKI_API_KEY; it refuses to start without them. Optional tuning:

  • CHINASKI_MCP_SESSION_TTL: session lifetime in seconds (default 86400).
  • CHINASKI_MCP_SESSION_DB: session database path (default chinaski-mcp/sessions.db).
  • CHINASKI_MCP_LOG_DIR / CHINASKI_MCP_LOG_FILE: log location (defaults logs/ and logs/mcp-server.log).
  • CHINASKI_MCP_MAX_RETRIES: default 3.
  • CHINASKI_MCP_CONTEXT_TTL: site-context cache lifetime in seconds (default 300).

Backups and deploys

Used by deploy/backup.sh:

  • CHINASKI_BACKUP_DIR: backup destination; default /var/backups/chinaski<N>.
  • CHINASKI_BACKUP_RETENTION_DAYS: how long database snapshots are kept; default 14.

Used by deploy/deploy.sh:

  • CHINASKI_ALLOW_BUILD_FAIL=1: normally a failed build aborts the deploy so the service never restarts on stale or partial output; this flag continues anyway in an emergency.

Warnings

  • Keep /etc/chinaski<N>/env at mode 0600. Backups contain the full database (password hashes, encrypted secrets); the backup script tightens the backup directory to 0700 on every run; make sure nothing else widens it.
  • CHINASKI_AIRGAP=1 silences outbound traffic entirely; set it before first start if your deployment never touches the internet.
  • Rotating CHINASKI_SECRET is a deliberate event, not routine maintenance: sessions die and encrypted settings need re-saving.
Read this site in