chmonitorDocker
Run chmonitor as a Docker container or Compose service — the fastest path to a self-hosted ClickHouse dashboard.
Run chmonitor as a Docker container — the fastest path to a self-hosted ClickHouse dashboard. The image is published to GitHub Container Registry.
Prerequisites
- Docker installed and running.
- A reachable ClickHouse endpoint with a monitoring user (
SELECTonsystem.*). - A release tag to pin.
Image and tags
Image: ghcr.io/chmonitor/chmonitor:vX.Y.Z — replace vX.Y.Z with a real release tag. Browse all releases.
The legacy name ghcr.io/chmonitor/chmonitor also works and points at the same build.
Setup
Pull and run
docker run -d --name chmonitor -p 3000:3000 \
--add-host=host.docker.internal:host-gateway \
-e CLICKHOUSE_HOST='http://host.docker.internal:8123' \
-e CLICKHOUSE_USER='monitoring' \
-e CLICKHOUSE_PASSWORD='change-me' \
ghcr.io/chmonitor/chmonitor:vX.Y.ZOpen http://localhost:3000.
Linux host networking
--add-host=host.docker.internal:host-gateway is needed on Linux when ClickHouse runs on the Docker host. It is not needed on Docker Desktop for Mac/Windows.
services:
chmonitor:
image: ghcr.io/chmonitor/chmonitor:vX.Y.Z
ports:
- '3000:3000'
environment:
CLICKHOUSE_HOST: 'http://clickhouse:8123'
CLICKHOUSE_USER: 'monitoring'
CLICKHOUSE_PASSWORD: 'change-me'
healthcheck:
test: ['CMD', 'wget', '-q', '-O', '/dev/null', 'http://localhost:3000/api/health']
interval: 30s
timeout: 5s
start_period: 20s
retries: 3If ClickHouse runs in the same Compose project, use the service name as the host. If it runs on the Docker host machine, use host.docker.internal and add --add-host=host.docker.internal:host-gateway to the service's extra_hosts.
Verify
curl -sf http://localhost:3000/api/healthz && echo OKConfigure
Pass env as -e, a Compose environment: block, or env_file: .env. Required:
CLICKHOUSE_HOST CLICKHOUSE_USER CLICKHOUSE_PASSWORDTemplate: apps/dashboard/.env.example.
Full names: Environment variables.
Auth, agent, and feature flags: Authentication and
Feature permissions.
Clerk / dual-surface flags need a custom image
CHM_AUTH_PROVIDER and CHM_CLERK_PUBLISHABLE_KEY are inlined at build time.
The GHCR image is none. Enable Clerk by building your own image with those
set, then pass CLERK_SECRET_KEY at runtime.
Upgrading
Pull the new tag
docker pull ghcr.io/chmonitor/chmonitor:vX.Y.ZStop and remove the old container
docker rm -f chmonitorStart with the same env vars
docker run -d --name chmonitor -p 3000:3000 \
-e CLICKHOUSE_HOST='...' \
... \
ghcr.io/chmonitor/chmonitor:vX.Y.ZOr with Compose: update the image: tag, then docker compose up -d --force-recreate.
For breaking changes between major versions, see Migrating to v0.3.
Troubleshooting
localhost resolves to the container
localhost inside the container resolves to the container itself, not the host. Use host.docker.internal.
- Empty pages usually mean the ClickHouse user lacks grants on system tables. Grant
SELECTonsystem.*. - If pages load but charts are empty, check
CLICKHOUSE_MAX_EXECUTION_TIME— the default is 60 s.