Docs

Deploy & operate

Postgres by default, ClickHouse at scale, your object store and secret manager, and the model provider you choose, or none.

InsightClickIQ runs in your own cloud account or data centre: an API (FastAPI) that also serves the SDK, a React console, Postgres, and an object store for replays and PDFs. Every choice below is configuration.

One machine with Docker Compose

GIT_TOKEN=… CLICKIQ_ADMIN_EMAIL=you@company.com docker compose up --build
# the API on :8124 (OpenAPI at /docs, the SDK at /sdk/clickiq.js)

# large deployments: ClickHouse for the event table
docker compose --profile clickhouse up --build     # then CLICKIQ_EVENT_STORE=clickhouse on the api

The compose file is the template for a pilot: Postgres 16 with an ordinary application role (so row-level security binds), and the API. The console is a React application that talks to the API under /api.

Configuration

Variable	Purpose
`INSIGHT_DATABASE_URL`, `_SECRET`, `_SCHEMA`, `_SSLMODE`	Postgres for everything (schema `clickiq`); the password as a secret reference
`CLICKIQ_REPLAY_STORE`	Where replay bodies and PDFs go: `s3://`, `az://`, `gs://`, `oci://`, `s3+http://` (MinIO, Ceph) or `file://`
`CLICKIQ_READ_DATABASE_URL`	A read replica for console reads; unset means the primary
`CLICKIQ_EVENT_STORE`	`postgres` (default) or `clickhouse`, with `CLICKIQ_CLICKHOUSE_URL`, `_SECRET`, `_WRITE_URL`, `_TTL_DAYS` (400) and `CLICKIQ_EVENT_DUAL_WRITE`
`CLICKIQ_RETENTION_ENABLED`, `CLICKIQ_RETENTION_HOUR`	The daily retention round (on; 3 a.m. local); per-project `retention_days`
`INSIGHT_LLM_PROVIDER`	The model provider: Bedrock (default), Azure OpenAI, Vertex, OCI or an OpenAI-compatible endpoint
`CLICKIQ_AI=false`	No model at all: every AI surface answers by rules
`CLICKIQ_CONSOLE_URL`, `CLICKIQ_PDF`	Where the console runs (for server PDFs, email buttons and share links); `off` disables server printing
`CLICKIQ_EMAIL_PROVIDER`	`smtp` or `ses`; unset means SMTP when `CLICKIQ_SMTP_URL` is set, otherwise email is off
`CLICKIQ_SMTP_URL`, `CLICKIQ_SMTP_SECRET`	`smtp://user@host:587` (STARTTLS when offered) or `smtps://user@host:465`; the password as a secret reference
`CLICKIQ_SES_REGION`, `CLICKIQ_EMAIL_FROM`	Amazon SES region; the sender address
`CLICKIQ_EXPORT_INTERVAL_MINUTES`, `CLICKIQ_EXPORT_MAX_ROWS`, `CLICKIQ_EXPORT_LAG_SECONDS`	How often the export round checks for due jobs (10); rows per run before it continues next round (1,000,000); how old an event must be before export (60 s)
`CLICKIQ_EXPORT_FILE_DESTINATIONS`	Allow `file://` export destinations; set `false` outside development
`CLICKIQ_ALLOW_PRIVATE_WEBHOOKS`	Off by default: webhooks and S3-compatible export endpoints on private, loopback or metadata addresses are refused; set `true` on a laptop or for an internal MinIO

Secrets are references, resolved at start: aws-sm://, azure-kv://, gcp-sm://, oci-vault://, or file:// and environment variables on-premises.

Sizing

Measured footprint: about 0.9 KB per event in Postgres with indexes (271k events took 246 MB). Replays live in the object store at 50–300 KB per recorded session.

Traffic	Events / month	Recommended
Internal app, small site	0.1–2 M	One small managed Postgres (2 vCPU, 8 GB)
Mid-size product or store	2–30 M	Postgres 4–8 vCPU with monthly partitions and a read replica
Large site, many tenants	30–300 M	Postgres to about 100 M a month; above that, ClickHouse for the event table
Very large multi-tenant	> 300 M	ClickHouse for events; Postgres for sessions, people and content

The event store: Postgres or ClickHouse

Variable	Default	Meaning
`CLICKIQ_EVENT_STORE`	`postgres`	`postgres` (the partitioned `event` table under row-level security) or `clickhouse`
`CLICKIQ_CLICKHOUSE_URL`	—	`clickhouse://user@host:8123/db`; `clickhouses://` for TLS (8443)
`CLICKIQ_CLICKHOUSE_SECRET`	—	The password as a secret reference (`aws-sm://`, `azure-kv://` …)
`CLICKIQ_CLICKHOUSE_WRITE_URL`	the URL above	A writer for ingest and backfill; give the console a read-only user
`CLICKIQ_CLICKHOUSE_TABLE`, `_TTL_DAYS`	`clickiq_event`, 400	The table and ClickHouse’s own retention
`CLICKIQ_EVENT_DUAL_WRITE`	on with ClickHouse	Also write Postgres (needed for sessions, people and the Postgres-only reads); on a Postgres store, shadow-write ClickHouse to warm it

The query engine has one builder and two dialects, so the same QuerySpec compiles to Postgres or ClickHouse. Turn on dual-write with Postgres as the store to warm ClickHouse, backfill history with scripts/backfill_clickhouse.py, then set CLICKIQ_EVENT_STORE=clickhouse. ClickHouse has no row-level security, so every generated statement must carry the organisation predicate; the engine refuses one that does not. Give the console a read-only ClickHouse user and ingest a writer. In the demo, a person-trait breakdown went from 957 ms on Postgres to 54 ms.

Warehouse exports

Exports (console Exports, or /api/exports) copy a project’s event, session and person tables incrementally to an object store you own, hourly or daily, as Parquet (snappy) or gzipped NDJSON.

s3://bucket/prefix              az://account/container         gs://bucket
oci://namespace/bucket          s3+https://minio.internal:9000/bucket

<destination>/project=<id>/table=event/dt=YYYY-MM-DD/part-<cursor>.parquet
<destination>/project=<id>/table=session/dt=YYYY-MM-DD/part-<cursor>.parquet
<destination>/project=<id>/table=person/dt=YYYY-MM-DD/part-<cursor>.parquet
<destination>/project=<id>/_runs/<run id>/_manifest.json

Events are exported by id; sessions and people by their last change, so a changed row is exported again (keep the latest modified per id in the warehouse). A run that is interrupted rewrites the same file. Test destination writes, reads back and deletes a probe file. GET /api/exports/schema returns every column with its Parquet, Athena and BigQuery type and the CREATE EXTERNAL TABLE statements (Athena with partition projection, BigQuery hive-partitioned); Synapse and Snowflake read the same files.

Email

What	How to turn it on
Alerts	Add addresses to an alert’s email channel; it mails on every state change (firing, resolved) with the value, the condition and the metric’s trend
Weekly digest	A project’s `digest_email` list (Volume & email card); sent once a week with the narrative, KPIs, live signals and a chart
Email this report	`POST /api/reports/{id}/email {to, range, note, attach_pdf}`; the PDF is attached when it renders

Every message has text and HTML parts with a button back to the console, at most 20 recipients, and an inline chart when matplotlib is installed. A delivery failure is logged and never fails an alert check.

Sampling

For very high volume, set a project’s Sessions kept (sample_rate, 0 < r ≤ 1) on the Volume & email card. Every SDK keeps or drops whole sessions by the same hash of the session id; kept events carry the rate. Counts and sums are weighted (each kept session counts 1/r), people and sessions are estimated, and every sampled chart and Overview tile says so. Averages, percentiles, funnels, retention and paths are computed on the sample. Errors and conversions are not exempt; a project that must see every error keeps 100% and scales with ClickHouse.

Health, retention and erasure

Endpoint	What
`GET /api/health`, `/api/health/readiness`	Liveness; readiness including the event store and dual-write counters
`GET /api/health/config`	The effective event store, URL without password, table, TTL, dual-write
`GET /api/health/retention`	The last retention run and every partition with its size (admin)
`DELETE /api/sessions/{id}`	Erase one session: events and replay objects
`DELETE /api/people/{id}`	Erase a person: every id they used, their sessions, events and replay objects

For the managed services on each cloud, see Cloud & on-prem.