# 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](/docs/integration/analytics/server/setup#run-a-self-hosted-server).

## 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:

```toml
[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:

```sh
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:

```sh
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:

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

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

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

To replace a key immediately while retaining its ID:

```sh
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:

```sh
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](https://github.com/chunkifydev/chunkify-analytics/blob/v0.18.0/docs/administration.md#backup-and-restore).

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

```sh
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](https://github.com/chunkifydev/chunkify-analytics/blob/v0.18.0/docs/storage.md#upgrade-the-schema).

## 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.