Skip to content

Install with Docker

The Docker path generates a self-contained Compose directory. Click-Dog runs as a container, while its editable YAML and ClickHouse credential stay on the host.

Prerequisites

  • a Linux host with Docker Engine and Docker Compose
  • ClickHouse reachable from that host
  • an OTLP/gRPC receiver address
  • a ClickHouse monitoring user with SELECT on system.opentelemetry_span_log and system.query_log
  • the ClickHouse password in CLICKHOUSE_PASSWORD

The generated Compose service uses host networking, so its default clickhouse.host: localhost reaches ClickHouse on the same Linux host. Edit the generated config before starting when ClickHouse is elsewhere.

Generate the deployment

If click-dog is available on the machine where you prepare deployment files:

export CLICKHOUSE_PASSWORD="your-monitoring-password"
click-dog deploy docker -c otel-collector.internal:4317

For a fresh machine, the release installer can run the same generator from the published container image:

curl -fsSL https://github.com/coltconsulting/click-dog/releases/latest/download/install.sh -o install.sh
export CLICKHOUSE_PASSWORD="your-monitoring-password"
bash install.sh docker -c otel-collector.internal:4317

The installer wrapper requires Docker plus envsubst from the gettext package. It generates files only; it does not install a host binary or systemd service.

Both paths create click-dog-docker/ containing:

  • docker-compose.yml with an exact Click-Dog image tag
  • click-dog.yaml, mounted read-only into the container
  • .env, containing the ClickHouse password
  • .gitignore, which excludes .env and update backups

The Go generator writes .env with mode 0600. Treat the whole output directory as deployment configuration and never commit .env.

Use -o DIR / --out-dir DIR to choose another output directory, -u USER for another ClickHouse username, or -v VERSION to pin a release. Prefer the environment variable over -p: a password flag appears in process listings and shell history.

Review and start

Review click-dog.yaml, particularly the ClickHouse address, OTLP receiver, TLS, and query-text posture. Then start Compose:

cd click-dog-docker
docker compose up -d

The service uses restart: unless-stopped and mounts only the generated config.

Verify

Check container state and logs:

docker compose ps
docker compose logs --tail=50 click-dog

Run the config and data-path checks inside the container:

docker compose exec click-dog \
  click-dog validate --config /etc/click-dog/click-dog.yaml

docker compose exec click-dog \
  click-dog check --config /etc/click-dog/click-dog.yaml

The generated config enables health on :8686 and Prometheus metrics on :9090. With host networking they are reachable on the Docker host unless you change those listener addresses.

Update

Resolve the latest stable version, update only the Compose image reference, review the generated backup, then recreate the service:

LATEST_URL="$(curl -fsSL -o /dev/null -w '%{url_effective}' \
  https://github.com/coltconsulting/click-dog/releases/latest)" || exit 1
VERSION="${LATEST_URL##*/v}"

click-dog deploy docker --update -v "$VERSION" -o click-dog-docker
cd click-dog-docker
docker compose up -d

The update creates docker-compose.yml.bak and changes only the image tag. It does not merge or rewrite click-dog.yaml. See Updating for the shared config-default and prerelease contract.

If only the installer wrapper is available, the equivalent generator command is:

bash install.sh docker update -v "$VERSION" -o click-dog-docker

Remove

Stop and remove the Compose service from its generated directory:

cd click-dog-docker
docker compose down

After retaining any configuration you need, remove the generated directory through your normal file-management workflow. click-dog deploy uninstall is for the standard systemd installation and deliberately does not touch Docker.