docs · get started
Run Chirkle on a server
Give Chirkle a domain and it serves HTTPS on its own, with a certificate from Let's Encrypt. On a Linux server, one command installs it as a systemd service that starts on boot and restarts if it stops.
Prefer containers? See Docker or Dokku. Already running nginx or Caddy? See Behind a reverse proxy.
What you need
- A Linux server. One CPU and 1 GB of RAM is plenty: that holds about 1,000 people chatting at a normal pace (Performance).
- Node.js 22 or newer and npm 11 or newer on it.
- A domain pointing at it: an
Arecord (andAAAAfor IPv6) for, say,chat.example.comwith the server's IP. - Ports 80 and 443 open.
- Optional:
ffmpegandcurl, for video thumbnails and link previews. On Debian or Ubuntu:sudo apt install ffmpeg curl.
Install it
$ sudo npx chirkle install-service chat.example.com
This:
- copies the server and the web app to
/opt/chirkle; - creates a system user,
chirkle, which owns the data folder/opt/chirkle/pb_dataand nothing else; - writes
/etc/systemd/system/chirkle.service, sandboxed so the service can't write anywhere but its data; - enables and starts it.
The first visit to https://chat.example.com fetches the certificate. Then create the admin account:
$ sudo -u chirkle /opt/chirkle/chirkle-server superuser upsert you@example.com <password> --dir=/opt/chirkle/pb_data
Sign in to the admin UI at https://chat.example.com/_/, and go through Administration: set the
Application URL, your name and logo, signups, email and backups.
Logs: journalctl -u chirkle -f.
Options
| Flag | What it does |
|---|---|
--dry-run | Prints the unit file and what it would do, and changes nothing. Use it to review the setup, or to write the unit yourself. |
--http=127.0.0.1:8090 | No domain: listen on a local address for a reverse proxy on the same machine (Behind a reverse proxy). This is also what happens when you give no domain. |
--prefix=<dir> | Install somewhere other than /opt/chirkle. |
--data=<dir> | Keep the data somewhere other than <prefix>/pb_data. |
--user=<name> | Run as a user other than chirkle. |
--name=<unit> | Name the service something other than chirkle, to run several side by side. |
Any other flag goes to the server.
Settings
Environment variables, such as those for the Telegram bridge or turning off link previews, go in an override that survives reinstalls:
$ sudo systemctl edit chirkle
[Service]
Environment=TELEGRAM_BOT_TOKEN=123456:ABC…
Environment=FFMPEG=off
Most other settings live in the admin UI. The configuration reference lists both.
Update
Take a backup first, then run the install again with the latest version:
$ sudo npx chirkle@latest install-service chat.example.com
The files are replaced and the service restarted. Your data stays. Database changes (migrations) run on their own when the server starts, and it serves nothing until they're done.
Give the same flags you installed with, if any.
Uninstall
$ sudo npx chirkle uninstall-service
This stops, disables and removes the service. The files and the data stay in /opt/chirkle for you to delete.
By hand
The server is PocketBase with Chirkle's busiest code built in, so it takes the same commands and flags as the
pocketbase binary. To run it under another init system, or on a machine without Node:
- Build it once, on any machine with Node and Go 1.27+, from a clone of the
repository:
$ npm ci && npm run setup && npm run buildFor another platform,
node scripts/build-server.mjs --allbuilds every one intobin/release/. - Copy the server and its folders:
$ rsync -a bin/chirkle-server pb_public pb_migrations pb_hooks server:/opt/chirkle/ - Run it, with the capability to bind ports 80 and 443 (
CAP_NET_BIND_SERVICE):$ /opt/chirkle/chirkle-server serve chat.example.com --hooksPool=100 \ --dir=/opt/chirkle/pb_data --publicDir=/opt/chirkle/pb_public \ --migrationsDir=/opt/chirkle/pb_migrations --hooksDir=/opt/chirkle/pb_hooks
npx chirkle install-service chat.example.com --dry-run prints a systemd unit with these settings that you can start
from.