docs · reference

Configuration reference

Chirkle is configured in three places:

  • Environment variables, read when the server starts. Change them and restart.
  • The site record, under Collections → site in the admin UI. Changes apply at once.
  • The admin UI's settings, under Settings. Changes apply at once.

How to set environment variables depends on how you run Chirkle: before the command with npx, sudo systemctl edit chirkle with systemd, -e with Docker, dokku config:set with Dokku.

Environment variables

Running the server

VariableDefaultWhat it does
HOST127.0.0.1The address npx chirkle listens on. 0.0.0.0 reaches it from other machines.
PORT8090The port npx chirkle listens on.
CHIRKLE_DATA./pb_dataWhere npx chirkle keeps its data.
TRUSTED_PROXYnot set (the Docker image: X-Forwarded-For)The header a reverse proxy puts the visitor's address in, usually X-Forwarded-For. off trusts none. Not set, the admin UI's setting stays. Set it only with a proxy in front: see Behind a reverse proxy.

HOST, PORT and CHIRKLE_DATA are read by npx chirkle. Running the server binary yourself, use its --http and --dir flags instead.

Features

VariableDefaultWhat it does
LINK_PREVIEWSonoff turns link previews off.
FFMPEGonoff turns video thumbnails off.
TELEGRAM_BOT_TOKENnot setThe bot's token. Turns the Telegram bridge on.
TELEGRAM_WEBHOOK_URLnot sethttps://<your domain>/api/telegram/webhook. Not set, the bridge polls Telegram, which is meant for local testing.
TELEGRAM_WEBHOOK_SECRETmade from the tokenWhat Telegram sends with each webhook call.
ANDROID_CERT_SHA256not setThe SHA-256 fingerprints (comma-separated) of the keys your build of the Android app is signed with, so your server's links open in the app.
ANDROID_APP_IDcom.chirkle.androidYour build's app ID, if you changed it.

Performance

VariableDefaultWhat it does
GOMEMLIMIT70% of the machine's memoryThe memory the server aims to stay within, for example 700MiB. Not set, it uses 70% of the memory limit of its container, or of the machine's RAM.
GOGC200How far the memory grows between garbage collections, as Go defines it.
CHIRKLE_ADMISSIONonoff lets every request run at once, instead of queueing those past what the server can usefully run together. Leave it on: see Performance.

For development and tests

STATS_CRON, MEDIA_CRON and ACCOUNT_CRON (off stops a background job, for tests that run it themselves), FEDERATION_ALLOW_PRIVATE, LINK_PREVIEWS_ALLOW_HOSTS and TELEGRAM_API_BASE (point the server at local test servers), CHIRKLE_LEGACY (answer as an old server does) and CHIRKLE_PPROF (serve Go's profiler on a local address, for load tests). Don't set them in production.

Command-line flags

The server is PocketBase underneath, so chirkle-server serve takes PocketBase's flags. npx chirkle passes any it doesn't know on to it. The useful ones:

FlagWhat it does
chat.example.com (a domain, first)Serve HTTPS on ports 80 and 443, with a certificate from Let's Encrypt.
--http=<address>Serve plain HTTP on this address, for example 127.0.0.1:8090.
--https=<address>Serve HTTPS on this address.
--dir=<folder>The data folder.
--hooksPool=<n>How many requests can run the server's scripts at once. Chirkle's setups use 100.

For the one-command systemd install's flags (--dry-run, --prefix and others), see Run it on a server.

Other commands: superuser upsert <email> <password> creates or updates an admin account; migrate, update and the others are PocketBase's own (--help lists them).

The site record

Collections → site in the admin UI has one record:

FieldWhat it does
titleThe server's name, up to 48 characters: in the app bar, on the login page, in the tab's title. Branding
logoAn SVG, PNG, JPEG, WebP or GIF of up to 1 MB, replacing Chirkle's logo.
invite_onlySigning up needs invite_code. Invite-only signups
invite_codeThe code. Empty while invite_only is ticked: signups are closed.
no_statsStop recording usage statistics.
federationTurn linking with other servers on.
min_android_versionOlder Android apps ask to be updated. For admins

Per record

WhereFieldWhat it does
Collections → usersmoderatorMakes the person a moderator.
Collections → usersbannedBans them: they're signed out and can't sign in.
Collections → roomsanonymousMakes the room anonymous.

The admin UI's settings

SettingWhat for
Settings → Application → Application URLYour server's public address. Needed for password reset emails and linking.
Settings → Application → trusted proxyThe same as TRUSTED_PROXY, when that isn't set.
Settings → Mail settingsEmail.
Settings → Files storageKeep uploaded files on S3.
Settings → BackupsBackups.
Settings → Rate limitsRate limits.

Edit this page on GitHub