Operate your server

Operating your server

Keep the data directory persistent, back it up, and leave enough server capacity for your connected machines.

Preserve the whole data directory

The container stores its state under /data, mounted as ./data in the quickstart. This includes the SQLite database, run output, and the generated app.key.

The application key is needed to read encrypted values such as job environment variables. A database backup alone does not preserve that key.

Follow the backup and restore guide for consistent backups, including backups while the server is running.

Upgrade the server

Read the server changelog, back up your data, then run:

docker compose pull
docker compose up -d

Database migrations run automatically on startup. Check the release notes for agent compatibility requirements.

Size for your machines

Each connected agent occupies a request thread while it waits for work. The default FRANKENPHP_NUM_THREADS: 32 leaves room for roughly 25 machines, with the remaining threads serving browser requests and agent reports.

Increase the thread count above your machine count with headroom as you grow. Reducing the polling wait time does not remove the need for those threads. The installation reference explains the limit.

Check server health

The /up endpoint returns HTTP 200 when the server is ready. To inspect container logs:

docker compose logs -f

Retention, the default timezone, and output caps are configured in Settings → General. See the operations reference for scheduling behavior and maintenance commands.