Docs

Administration

Manage your Analytics Server.

Chunkify maintains hosted analytics. Manage its keys and website origins in Analytics > Settings.

For self-hosting, you manage retention, backups, and upgrades. Run the commands below from the stack directory of the Docker Compose setup.

Data retention

Hosted analytics uses your team's analytics retention policy, shown in the server's settings. This policy is independent of media-file retention.

Self-hosted retention defaults to 30 days by server receipt time. Configure the installation default in the existing TOML section:

[retention]
seconds = 5184000
interval_seconds = 3600

This example keeps events for 60 days. Set seconds = 0 to disable expiration for projects inheriting the default. Run docker compose restart analytics to apply installation changes.

Change one analytics project's policy while the server runs:

docker compose exec analytics \
  chunkify-analytics project retention default 604800

The example selects seven days. Use 0 for unlimited retention or inherit to restore the installation default.

Changes apply to existing and new events. Shortening retention makes older events eligible for cleanup; extending it cannot recover deleted data.

Reports hide expired events immediately, and a periodic sweep deletes them.

Rotate credentials

For hosted analytics, open the saved server's Keys or MCP tab. Rotate the relevant key and save any new private value when it is shown. The old key stops working immediately.

For self-hosting, create a replacement public key:

docker compose exec analytics \
  chunkify-analytics key create default public "Website v2"

Save the returned key_id and key. Deploy that public key to your tracker, then revoke the old key by its ID:

docker compose exec analytics \
  chunkify-analytics key revoke default OLD_KEY_ID

Create a private read-only key for an application or MCP client:

docker compose exec analytics \
  chunkify-analytics key create default secret "Application reports" --read-only

To replace a key immediately while retaining its ID:

docker compose exec analytics \
  chunkify-analytics key rotate default KEY_ID

The replacement is returned once. Listings show metadata and IDs, not key values. Use chunkify-analytics project list to find the project and key IDs. Changes made on one server apply to every server sharing the database within a few seconds.

Keep full-access secret keys for administration. An analytics project's public, read-only API, and MCP credentials have different purposes; rotate the one used by the affected client.

Back up and restore

The ClickHouse database holds all events, analytics projects, and key hashes; analytics servers keep no data. Keep backups private, and save config.toml, .env, and your keys separately.

Stop the stack and archive its clickhouse-data volume:

docker compose stop
umask 077
docker run --rm \
  --mount type=volume,src=chunkify-analytics_clickhouse-data,dst=/var/lib/clickhouse,readonly \
  --entrypoint tar clickhouse/clickhouse-server:26.10 -C /var/lib/clickhouse -czf - . \
  > analytics-backup.tar.gz
docker compose start

To back up without stopping the server, use ClickHouse's BACKUP command instead. See the backup reference.

To restore, extract the archive into an empty chunkify-analytics_clickhouse-data volume, such as on a new host, before starting the stack:

docker volume create chunkify-analytics_clickhouse-data
docker run --rm -i \
  --mount type=volume,src=chunkify-analytics_clickhouse-data,dst=/var/lib/clickhouse \
  --entrypoint tar clickhouse/clickhouse-server:26.10 -C /var/lib/clickhouse -xzpf - \
  < analytics-backup.tar.gz
docker compose up -d

Do not run init on a restored database. Check health and reports before sending traffic. A restore also restores old key and retention state; reapply later changes as needed.

Upgrade a self-hosted server

  1. Take a backup of the database and your configuration.
  2. Set CHUNKIFY_IMAGE in .env to the new image version. If the release changed compose.yaml, Caddyfile, or clickhouse.xml, update those files and keep your config.toml and .env. Keep the previous version available for rollback.
  3. Run docker compose run --rm analytics migrate to apply the release's database schema migrations. The servers already running keep serving meanwhile.
  4. Run docker compose up -d to replace the containers. The clickhouse-data volume is kept.
  5. Check health, reports, and new event delivery before returning it to use.

A server does not start on a database that still needs migrations; its log says to run migrate. Migrations cannot be undone, so rolling back after one means restoring the pre-upgrade backup. See the schema upgrade reference.

Remove a saved server

Removing a hosted server deletes its analytics project and invalidates its keys. Stored events expire under the project's existing retention policy; removal does not immediately erase retained events.

Removing a self-hosted server from Chunkify removes the saved connection settings. Your server, analytics project, events, and keys remain in your infrastructure.