Quickstart

A brand-new site on any Debian/Ubuntu server, without prerequisites, in one command:

curl -fsSL https://chinaski.net/install | sudo bash -s -- 1 --repo https://github.com/bigjohncobb/chinaski

Replace 1 with an instance name: anything alphanumeric (2, prod, staging, a client’s name). Each instance is its own isolated site with its own database; running several at once is normal. The script needs no prior setup and completes in under five minutes.

What the script does

It handles everything itself:

installs the required system packages and Perl dependencies (from pre-built Debian packages, no C compilation)
creates a dedicated chinaski system user
clones the code, initialises the database, writes the env file
starts the systemd service

After it finishes, point a browser at the admin and continue via /setup: change the admin password (at least 12 characters, mixed case plus a digit), set the site URL, and pick your languages. That’s your first site ready to edit; the build happens when you click it.

Day-one checklist

Verify these before sending real traffic:

The admin is loopback-bound. A listening socket check should show 127.0.0.1:300<N>, never 0.0.0.0; visitors must not reach the CMS directly from outside.
TLS certificate issued. The example Caddyfile installed per instance reads your DNS and renews Let’s Encrypt certificates; check curl -I https://<host> once DNS and ports 80/443 resolve and respond.
Backups are scheduled. An automatic daily snapshot of the database plus media runs at 03:17: check the systemd timer is on, and that the backup directory is mode 700 and owned by the service user. If you edit the clock schedule manually, confirm systemctl list-timers shows a next run; a typo makes the timer silently skip.
Notify your monitor about /health. The CMS’s health endpoint returns an aggregated JSON report ({"status":"ok|warning|critical", timestamp, total_checks, checks[]}) with HTTP 503 only when a critical check fails. (The separate Chinaski Manager has its own /health returning status/uptime/db/workers/pid on the control-plane port.)
Timezone: set from /admin settings. Schedules use the site timezone; typo’d timezone names fall back to UTC at save time; check it, then keep all your scheduled entries correct.

Two environment variables matter in /etc/chinaski<N>/env (mode 0600): CHINASKI_SECRET: the 32+ byte random session-signing key, and LISTEN_URL, which must point at loopback in production. Database and output paths derive from the instance name by the unit; you usually needn’t override them.

Other routes to running Chinaski

Fully offline first-run: an install script can be used on a machine without internet by preparing a bundle first: run bash install/make-bundle.sh on a connected box, which produces a tarball containing the app source, all Perl module tarballs, bundled cpanm, and the install script plus a checksum file. After copying to the target machine and untarring, run sudo bash install.sh: everything installs with no internet access. On ARM boards ( Raspberry Pi) explicitly install the image libraries (libjpeg, libpng, libgif), otherwise the image tooling fails to compile.
No systemd run: untar and run sudo bash install.sh --no-service (optionally --prefix /srv/chinaski), then start via the bundled hypnotoad; the admin answers at http://<host-ip>:8080/admin. The env file already contains the secret and air-gap mode.
Plain HTTP, forever: where no DNS and no certificate authority will ever exist, hypnotoad can serve directly over HTTP: no certificates to acquire, renew, or expire.

What happens next

The first visit to the admin redirects to /setup; once the placeholder password is replaced, that page disappears (it returns 404). From there the everyday edit → build → serve loop (see How It Works) takes over, and if you ever lose the admin password, perl bin/reset-admin.pl puts you right back into that same setup state.