1. Choosing a deployment mode #
From developer machine to production.
The options #
Available in: ✓ Open source ✓ Managed ClickStack Managed ClickStack: ClickHouse Cloud
| Mode | For | Limit |
|---|---|---|
| All-in-one | discover, demo, develop | one container: no scaling, no isolation; data lost without volumes |
| Docker Compose | small team, staging, single server | no high availability |
| Helm | production on Kubernetes | ClickHouse to operate (or external) |
| Managed ClickStack | not operating ClickHouse or the UI | beta in 2026; data in ClickHouse Cloud |
2. The all-in-one container #
ClickHouse, UI, collector and MongoDB together.
With persistence #
mkdir -p .volumes/db .volumes/ch_data .volumes/ch_logs
docker run -d --name clickstack --restart unless-stopped \
-p 8080:8080 -p 4317:4317 -p 4318:4318 \
-v "$(pwd)/.volumes/db:/data/db" \
-v "$(pwd)/.volumes/ch_data:/var/lib/clickhouse" \
-v "$(pwd)/.volumes/ch_logs:/var/log/clickhouse-server" \
clickhouse/clickstack-all-in-one:latest
# http://localhost:8080: create the first account (sources for the embedded database are created then)| Volume | Content |
|---|---|
/data/db | MongoDB: accounts, dashboards, alerts |
/var/lib/clickhouse | ClickHouse data (telemetry) |
/var/log/clickhouse-server | ClickHouse logs |
Watch out : Without volumes, everything is lost when the container is removed. Even with them, this mode is not for production: all processes share the same resources and cannot be sized or monitored separately.
Changing ports #
Only the host side changes: -p 4999:4318 publishes OTLP HTTP on port 4999. Changing UI (8080) or API (8000) ports also requires adjusting the matching variables.
3. Docker Compose #
One container per component.
Starting #
git clone https://github.com/ClickHouse/ClickStack.git && cd ClickStack
cat .env | grep -E 'IMAGE|PORT|VERSION' # image versions, UI, API and OpAMP ports
docker compose up -d
docker compose ps # app (interface + API), otel-collector, clickhouse, db (MongoDB)Useful variables (.env) #
| Variable | Role |
|---|---|
IMAGE_VERSION, CODE_VERSION | image version (pin it rather than latest) |
HYPERDX_APP_PORT | UI port (8080) |
HYPERDX_API_PORT | API port (8000) |
HYPERDX_OPAMP_PORT | OpAMP port driving the collector (4320) |
HYPERDX_APP_URL | public UI address (links in alerts) |
HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE | ClickHouse database for telemetry tables |
Using ClickHouse Cloud #
Remove the ClickHouse service from the Compose file (and its depends_on), then give the collector the service HTTPS address (port 8443) and credentials. Then create the connection in the UI (Team Settings) and the sources.
# ClickStack collector to a ClickHouse Cloud service (instead of the local database)
otel-collector:
image: clickhouse/clickstack-otel-collector:2
environment:
CLICKHOUSE_ENDPOINT: 'https://<service>.<region>.aws.clickhouse.cloud:8443'
CLICKHOUSE_USER: 'otel_writer'
CLICKHOUSE_PASSWORD: '${CH_PASSWORD}'
HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE: 'default'
OPAMP_SERVER_URL: 'http://app:4320'
ports: ['4317:4317', '4318:4318', '13133:13133']4. Kubernetes with Helm #
The clickstack chart (v2).
Scenarios #
| Scenario | Settings |
|---|---|
| Full stack | defaults: ClickHouse (operator-managed), collector, UI |
| External ClickHouse | clickhouse.enabled: false and connection via hyperdx.defaultConnections or an existing Secret |
| External collector | otel-collector.enabled: false and hyperdx.otelExporterEndpoint |
| UI only | ClickHouse and collector disabled, connection to existing ones |
# Add the ClickStack Helm repository (URL given in the “Helm” documentation), then:
helm install my-clickstack clickstack/clickstack -n observability --create-namespace -f values.yaml
# values.yaml: external ClickHouse (for example ClickHouse Cloud), collector provided by the chart
clickhouse:
enabled: false # do not deploy the embedded database (operator-managed)
hyperdx:
defaultConnections: | # UI connection to your ClickHouse (or an existing Secret)
[{ "name": "prod", "host": "https://<service>:8443", "username": "hyperdx", "password": "…" }]
otel-collector:
enabled: trueGood to know : The v1 chart (inline templates) is in maintenance: the documentation provides an upgrade guide to v2. Put passwords in a Secret (hyperdx.useExistingConfigSecret) rather than invalues.yaml.
5. Managed ClickStack and production #
Choosing and checking.
Managed ClickStack #
In ClickHouse Cloud, enable ClickStack on a service: the UI appears in the console, with its access control. You only deploy an OpenTelemetry collector near your applications, writing into the service. It is the simplest option if data can be hosted in ClickHouse Cloud.
Production checklist #
- Replicated ClickHouse (at least two replicas and ClickHouse Keeper) or ClickHouse Cloud; fast disks, object storage for cold data.
- Collectors sized for ingestion, several instances behind a load balancer, and a buffer queue if needed.
- MongoDB backed up (dashboards and alerts); TLS on the UI and on exposed OTLP endpoints.
- Retention (TTL) set per table and monitoring of ClickHouse itself (see the operations lesson).
- Pinned image versions and upgrades tested in staging.
Commands to know #
Commands to know
docker run … clickhouse/clickstack-all-in-one:latest: all-in-onedocker compose up -d: separate stackhelm install my-clickstack clickstack/clickstack -f values.yaml: Kubernetes deploymentcurl -s http://localhost:13133: collector healthdocker logs clickstack | tail: all-in-one container logs
Sources #
Checked in November 2026: ClickStack evolves fast (Managed ClickStack is in beta), check the ClickHouse documentation before relying on a detail.
My progress
Sign in to track your progress and take notes. Sign in
💬 Questions about this lesson
No questions yet: be the first to ask for help or share your configuration.
Recommended Articles
ClickStack: architecture, components and offerings (ClickHouse, HyperDX, OpenTelemetry)
ClickStack, ClickHouse's official observability stack: role of ClickHouse, the UI (HyperDX), the ...
SigNoz, ClickStack and ClickHouse best practices for observability
Best practices for observability on ClickHouse with SigNoz or ClickStack: OpenTelemetry instrumen...
Operating ClickHouse for ClickStack: sizing, replication, monitoring, security and backup
Running ClickHouse in production for observability: estimating volume and disk, replicating with ...
SigNoz: architecture and installation
SigNoz components (OpenTelemetry collector, ClickHouse, query service, interface, alerts), instal...
Observability on ClickHouse: why a columnar database changes the game
Why more and more observability platforms store logs, traces and metrics in ClickHouse: columnar ...
Operating an observability platform on ClickHouse and choosing a tool
Operate ClickHouse for telemetry (replication, disks, merges, object storage, monitoring) and com...
Alerts and dashboards in ClickStack
Building charts and dashboards in ClickStack, creating alerts on a search or a chart, sending the...
Sending telemetry to ClickStack: OpenTelemetry SDKs, collectors, logs, Kubernetes and browser sessions
Feeding ClickStack: ingestion key, OpenTelemetry SDK variables, forwarding through an existing co...
Telemetry in ClickHouse: schema, SQL, materialized views and retention
Telemetry in ClickHouse: otel_logs, otel_traces, otel_metrics_* and hyperdx_sessions tables, sort...