---
title: "Quickstart"
url: "https://docs.chinaski.net/en/start/quickstart/"
type: "page"
language: "en"
description: "Install a new Chinaski site on any Debian/Ubuntu server with one command, see what the script sets up, and take the first steps in /setup."
updated: "2026-09-29"
generated: "Markdown rendition of the HTML page at url, built by Chinaski"
---

# 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.
