Requirements
What a machine needs before it can run Chinaski: operating system, language runtime, database, and sizing. The short version: a Debian/Ubuntu box and Perl 5.26+.
Operating system
- Debian/Ubuntu family. Everything Chinaski needs, including every Perl dependency, is available from Debian stable packages, so a stock server installs with no compiler-side detours. The one-shot installer handles package installation itself; there is nothing to compile by hand.
- ARM boards (like Raspberry Pi) work, with one catch: the image libraries listed below need explicit installation, or the image-processing module won’t compile.
Perl and language-level requirements
- Perl 5.26 or later: the installers check this explicitly and refuse with an error message naming the found version if it’s older.
- The dependency set (all Debian-packaged, with exact minimums in the project’s cpanfile): Mojolicious, DBI + DBD::SQLite, Template (Template Toolkit), Crypt::Passphrase (+Bcrypt, +PBKDF2), CryptX, Imager, DateTime + DateTime::TimeZone, Archive::Tar, File::Copy::Recursive.
- Two optional modules power the Markdown importer only (CommonMark, which binds to the system cmark library, and YAML::PP). Without them the site boots and everything else works; only that one importer route shows a clear in-admin error.
System packages (manual/offline installs)
If you’re installing into an offline machine or manually from source, these apt packages are required first: perl, make, gcc, sqlite3, plus the image dev libraries (libjpeg, libpng, libgif); and for the online installer also openssl and cpanminus:
- make/gcc: used only when compiling the XS (native) modules at install time; the official installer uses pre-built Debian packages instead so no compilation is needed there.
- sqlite3: the database CLI, used for setup and maintenance.
- Image libraries: required from the Imager module’s native compilation.
The database
SQLite: embedded, no server process, no credentials to manage. Runs in WAL mode with a 64 MiB cache and a 5-second busy timeout, sized for the expected workload: one active admin session, periodic batch builds. Backup is a file copy.
Resource sizing
The shipped systemd units document the intended envelope and cap runaway processes:
| Component | Memory cap | CPU |
|---|---|---|
| CMS instance | 1 GiB (with 768 MiB soft limit) | 2 cores’ worth |
| MCP server | 512 MiB (384 MiB soft limit) | 1 core’s worth |
- Workers: the daemon runs 2 workers by default, sized “safe on a 1 GB machine”. If several editors will be on at once, the config accepts 4: comfortable on a 2+ GB host.
- Builds are separate processes with their own wall-clock limit (30 minutes hard) and a per-build write budget, so a single runaway build can’t starve the box indefinitely.
- Disk: two practical consumers dominate; the SQLite database (whatever your content weighs) and the static output tree (mirrored on rebuilds). Backup snapshots add roughly the compressed DB size per day under the default 14-day retention.
Ports and network posture
- Backend daemons bind high ports (3000-series by instance number by default; direct quick installs use 8080) and the reverse proxy owns 80/443; see the ports troubleshooting page for the exact allocation rules.
- After install, outbound calls ship off entirely in air-gap mode; internet connectivity is never required for the application to function.
Installation paths
- Debian/Ubuntu server: the one-line online installer (installs packages, creates the system user, clones, initializes the database, writes the env file, starts systemd).
- Offline: the documented offline bundle install on a place needing no Internet: mirror-only install from bundled tarballs with a SHA-256 checksum file to verify integrity.
- Quick local run: tar extract;
install.sh --no-service; run via bundled hypnotoad on port 8080; no systemd, no reverse proxy, no outbound calls needed.