Getting Started

Everything you need to go from zero to a published page: what Chinaski is, what machine it needs, how the install works, and the first things to click once you’re in the admin. Each section is short and aimed at the step it covers; the deeper reference lives in the linked pages.

The reading path

1. What Is Chinaski: the one-paragraph version: a self-hosted CMS + static site builder. Content in SQLite, admin in Perl, the public site plain HTML served by a web server.

2. How It Works: the two-program model (CMS app + static builder), why builds are explicit, and why the web server never talks to the CMS in the public path.

3. Requirements: the honest checklist: a Debian/Ubuntu server, Perl 5.26+, SQLite; sizing guidance and the two install paths (online one-liner or offline bundle).

4. Installation: the real install steps.

5. Quickstart: the five-minute path: install, change the setup password, create a page, build, publish.

6. Admin Tour: a map of the admin area: where pages, posts, blocks, stacks, forms, media, documents, settings, and the health screens live.

7. Your First Page: walking from a blank page list to a published page on the built site (draft → publish → build → verify).

8. Glossary: the vocabulary (blocks, stacks, snippets, promotion guard, trash vs delete) so the rest of the docs read faster.

The three decisions before you start

A few minutes of choosing saves rework later. These are the only configuration decisions that genuinely shape a new instance:

• Instance name: one server can run several Chinaski instances side by side (chinaski@1, chinaski@prod, …). The name shows up in install paths, service names, and backup targets forever.
• Languages: the configured language list drives URL shapes (path vs none vs subdomain) and per-language trees. Land the languagemet before content import: each content row belongs to exactly one language.
• Offline or connected: the air-gap switch defaults on in fresh installs. Decide before first start whether the instance is expected to reach the internet (email, webhooks, update checks, Spaces) or never should; air-gap mode ships enabled by default for a reason, and disabling it is a deliberate choice.

What “installed” means here

Chinaski is self-hosted by design: you own the server, the database, and the backups. The installer does the heavy lifting (system packages, dependencies, a chinaski system user, an initialized SQLite database, an env file with a generated secret, and a systemd unit), and the first request lands you on a mandatory setup page where you replace the placeholder admin password (enforced: 12+ characters with mixed case and digits). After that, the admin interface is yours; nothing phones home, and no other install-time step is required.

Where the docs continue

• Concepts: the architecture and content model behind the builder.
• Authoring: day-to-day content work: pages, posts, blocks, stacks, forms, media, documents.
• Deploy & Backup: serving the public site (nginx/Caddy), keeping it current, and keeping it recoverable.
• Troubleshooting & API: operational references when something doesn’t line up, and the machine interface for scripts and AI tooling.