Deployment & Operations
Running Chinaski in production: the systemd services, the reverse proxy in front of the public site, the deployment scripts, and the operational pages (logs, performance, air-gap, promotions) that keep it healthy. The section assumes the Getting Started install is done; it covers what you’re actually running.
In this section
- systemd Services: the templated instance units (
chinaski@<N>, backup, MCP), what they do, their hardening, and how to enable/restart them. - Reverse Proxy: the two proxy targets (static output + the CMS daemon), the routes that must forward (
/forms/,/documents/), the proxy headers that matter, and the Trust a real client IP rule. - The Hypnotoad Server: the server model (master + workers), the zero-downtime reload behavior, the shipped EOTW/offline config, and the daemon-vs-hypnotoad difference.
- Configuration: env-file conventions, the
LISTEN_URL/LISTEN, the secret handling, and the per-instance settings layout. - Static Hosting: serving the built output with nginx or Caddy; the
_redirectsformats and what routes a mostly-static site must still forward. - SSH / rsync Deploy: pushing built output to a remote host after every successful build.
- Publishing From a Phone: running the admin on an Android phone with Termux, publishing to Cloudflare R2 as the public host.
- Publishing From a Laptop: running the admin on a spare Linux laptop, publishing to Cloudflare R2 as the public host.
- Publish Your Site With Cloudflare R2: a step-by-step guide to publishing your site to Cloudflare R2: bucket, access keys, custom domain, rewrite rule and Chinaski deploy settings.
- Build & Publish Webhooks: firing webhooks on build/publish events to notify external systems.
- Air-gapped Mode: installing and running fully offline; what the switch disables; offline bundles and offline updates.
- Logs & Monitoring: journal logging, the health endpoints, build logs, and the metrics view.
- Performance: build parallelism, cache headers, database indexes, and the benchmark story.
- Promotion Guard: how a build refuses to degrade the live site (page drops, broken links, accessibility regressions) and the force/override paths.
How the pieces fit
The standard production layout is small:
- A systemd unit runs the CMS daemon bound to loopback (
LISTEN_URL=http://127.0.0.1:<port>). - A reverse proxy (Caddy or nginx) serves the public site from the static output tree, forwarding only forms/documents/admin-ish routes to the CMS daemon.
- Builds regenerate the static tree, triggered from the dashboard, a webhook, or the deploy script, and the deploy script (or rsync/S3 target) moves output to the serving location.
- Monitoring runs against the health endpoints, and air-gap mode (on by default in fresh installs) keeps the whole stack out of the outbound-call business unless explicitly opened.
The loop closes with backups (its own section) and deploys that fail safe: a failed build never re-starts the service on top of output that was never promoted. Thus, the whole operational story stays in two minutes of reading: what’s running, what’s served, what rebuilds it, how to keep both current, and where to look when they don’t.
Also in Deployment & Operations
Run Chinaski under systemd: the templated instance, backup and MCP units, what each does, and how to enable and restart them.
Put Caddy or nginx in front of Chinaski: serve the static site as plain files and forward forms, documents and the admin UI to the daemon.
Understand the production server model: master and workers, zero-downtime reloads, the shipped offline config, and hypnotoad versus the systemd daemon.
Set the six core environment variables per instance, handle secrets safely, and know which settings live in the admin instead.
Serve the built output from nginx, Caddy or any static host, including the _redirects files and the routes that must still reach the CMS.
Push the built site to a remote host over SSH after every successful build, with the safety rails and what happens on failure.
Send signed webhooks when a build finishes or scheduled content goes live, to trigger pipelines or refresh a CDN.
Install and run Chinaski with no outbound connections: what the switch disables, offline bundles, and signed offline updates.
Find your logs and watch the system: journald and security events, in-app build and auth history, and the health endpoints.
Tune build parallelism, cache headers and database indexes, starting with the changes that matter most.
Stop a bad build from replacing the live site: the four regression checks, their thresholds, and how to force a build past them.
Run Chinaski entirely on an Android phone with Termux, publishing the built site to Cloudflare R2.
Run Chinaski on a spare Linux laptop and serve the public site from Cloudflare R2, so it stays online when the laptop is off.
Publish your Chinaski site to Cloudflare R2 step by step: bucket, access keys, custom domain, rewrite rule and deploy settings.