Configuration

Manage servers in your Project's Analytics > Settings. Only Project owners can change them.

Projects

A saved server connects a Chunkify Project to one analytics project. Its credentials select the analytics project automatically; browser events do not need a project ID.

Hosted setup provisions the analytics project for you. For a self-hosted server, use public and read-only keys from the same analytics project.

To create another analytics project on a self-hosted server, run from the Docker Compose stack directory:

docker compose exec analytics \
  chunkify-analytics project create "Production website"
docker compose exec analytics \
  chunkify-analytics project list

Creation returns a generated project_id, public_key, and full-access secret_key. Save the keys privately when returned. Use that project ID when creating its read-only API or MCP keys.

Select a saved server when opening reports. Default for dashboard players independently selects where Chunkify previews, the playground, and newly generated player snippets send events.

Changing that default does not update players already deployed on your website.

Credentials

Key	Where it belongs	Access
Public Player key, ck_public_…	Playback tracker in the browser	Sends events to one analytics project.
Read-only API key, ck_secret_…	Your application backend	Reads analytics and creates CSV export links.
MCP key, ck_secret_…	Your private MCP client configuration	Reads analytics through MCP, separately managed from the API key.
Full-access secret key	Self-hosted administration backend or secret manager	Reads analytics and manages the analytics project's settings and keys.

In hosted settings, use the Keys tab for the Player and read-only API keys. Use the MCP tab for a separate MCP key and its endpoint. New private keys are shown once; save them before closing the dialog.

Rotation invalidates the previous key immediately. Update the clients that use it. Private keys never belong in player code.

For self-hosted servers, create and rotate keys on your server. The read-only key saved in Chunkify lets the dashboard query reports. It does not grant project or key management access.

Analytics keys are separate from Chunkify access tokens. The main Chunkify SDK manages saved analytics connections through the connection API.

Browser access

For hosted analytics, edit Allowed origins in the server's configuration. Chunkify dashboard origins are always allowed. Add every website origin from which you send events.

For self-hosted analytics, edit the existing section in config.toml:

[server]
allowed_origins = ["https://app.example.com", "http://localhost:3000", "https://chunkify.dev"]

Include the scheme and any port. Do not include paths, trailing slashes, or wildcards. localhost and 127.0.0.1 are different origins. A self-hosted project's additional origins extend the installation's shared list.

An empty combined allowlist denies browser requests carrying an Origin header.

Only POST /v1/events enables ingestion CORS. The server handles JSON and X-Chunkify-Ingest-Key preflight requests. Analytics reads belong on your backend, where the private key stays secret.

Configure your HTTPS proxy to forward the API and its OPTIONS requests without replacing the server's CORS responses. The tracker needs the full public ingestion URL, such as https://analytics.example.com/v1/events.

The public key authorizes event submission. Origin checks restrict browser access; they do not identify a viewer or authenticate the submitted measurements.

Browser and page context

The Chunkify adapter adds browser_context, including browser, OS, device, language, screen dimensions, and the current document's page_origin and page_path.

Page context excludes query parameters and fragments. In an iframe it describes the iframe document. Paths can still contain application identifiers; use collectBrowserContext: false to omit context for that destination.

Page context follows client-side navigation on subsequent events. A retry keeps the context serialized for the original event.

Location

The server derives approximate continent, country, and city from a local geolocation database. The lookup discards request IP addresses after use. Missing or private-address locations appear as null.

For self-hosting behind a proxy, configure the trusted proxy addresses or CIDRs in the existing [server] section:

trusted_proxies = ["10.20.1.2", "2001:db8:abcd::/48"]

The proxy must supply the real client address through X-Forwarded-For. Only trust proxy hops you control. Missing or invalid forwarded data can make location unavailable.

Pages displaying or using the bundled location results must include an IP Geolocation by DB-IP link. See the geolocation reference.

Self-hosted settings

Use config.toml for application settings. Environment variables cover the ClickHouse connection and secrets; in the Docker Compose stack, .env supplies the ClickHouse password. Run docker compose restart analytics after editing config.toml, or docker compose up -d after changing .env.

The Docker image reads /data/config.toml and sets CHUNKIFY_BIND=0.0.0.0:4174, which overrides server.bind.

TOML setting	Purpose
server.allowed_origins	Website origins permitted to send events.
server.public_url	External base URL used for CSV download links behind a proxy.
server.trusted_proxies	Proxy addresses trusted to provide client location context.
retention.seconds	Default receipt-time retention; 2592000 is 30 days and 0 disables expiration.
retention.interval_seconds	Interval between cleanup sweeps, in seconds.
rate_limits	Shared project read budgets, concurrency, and export limits.
mcp.allowed_hosts	Hostnames permitted to reach the MCP endpoint.
clickhouse.url, clickhouse.database	ClickHouse connection. Put the password in CHUNKIFY_CLICKHOUSE_PASSWORD.
clickhouse.rollup_max_lag_seconds	How long reports may lag stored events; 0 makes reports exact.
cache.report_ttl_seconds	Report cache lifetime on each server, from 0 to 60 seconds; 0 disables it.

For remote MCP access, add your hostname to the existing section:

[mcp]
enabled = true
allowed_hosts = ["localhost", "127.0.0.1", "[::1]", "analytics.example.com"]

Use the configuration reference for the complete settings, defaults, and bounds.

Storage and event delivery

ClickHouse stores events, analytics projects, and key hashes. Analytics servers keep no data, so several servers can share one database behind a load balancer. Ingestion succeeds after ClickHouse stores the events.

A repeated event ID received within the deduplication window, seven days by default, keeps its first payload.

Summary, engagement, quality, time-series, and video reports read hourly rollups and can lag stored events by about a minute. Set rollup_max_lag_seconds = 0 under [clickhouse] for exact reports, which cost more under load.

See the storage reference for scaling, replication, and these settings.

Ingestion responses

Response	Meaning
201	A new event was stored.
200	This event ID was already received within the deduplication window; the first payload is preserved.
400	The event is invalid. Send complete tracker events with the Chunkify adapter.
401	The public key is missing or invalid.
403	The website origin is not allowed for that analytics project.
413	The body or pending-write budget is exceeded.
415	The content type or encoding is unsupported.
429	An ingestion rate limit was reached.
503	The server is busy or unavailable. Inspect health and logs for a self-hosted server.

The Chunkify adapter sends individual JSON events. Use the OTLP adapter for external telemetry gateways. See delivery retries and limits.