Install Click-Dog¶

The standard installation is a guided setup for one Linux ClickHouse host. It installs a normal binary, YAML configuration, secret file, and systemd service. There is no Click-Dog control plane and no installer process left running.

Quick start¶

Download the current release installer, then run it:

curl -fsSL https://github.com/coltconsulting/click-dog/releases/latest/download/install.sh -o install.sh &&
sudo bash install.sh

Verify installer for instructions to authenticate install.sh before running it with sudo.

Safe to try, straightforward to change

The guide shows what it will create and waits for confirmation before the install step. It writes ordinary files in documented locations, leaves the configuration editable, and can remove the Click-Dog host files cleanly. ClickHouse-side changes are left for you to keep or remove deliberately. Starting here does not prevent you from later managing the same configuration through Ansible or moving the deployment to Docker or Kubernetes.

The installer always checks the downloaded binary archive against the release SHA-256 manifest. cosign is recommended, not required: when it is available, the installer also authenticates that manifest against Click-Dog's release workflow. See Verify releases if you want to authenticate install.sh itself before running it with sudo, require publisher authentication, or prepare an air-gapped installation.

Versions¶

install.sh takes the latest stable release, and prints the version it resolved before it installs anything.

You want	Flag
The latest stable release	none — the default
The most recently published beta	`--prerelease`
An exact version	`-v VERSION`

install.sh --prerelease takes the most recently published beta, while click-dog self-update --prerelease takes the highest version. These are normally the same release; they differ only when an older line is re-cut after a newer one, in which case pin the version you want with -v.

During the public beta the newest stable release can be older than the newest beta, so --prerelease is how you get the most recent build:

sudo bash install.sh --prerelease

The same applies to the installer itself: the Quick start URL above is served from the latest stable release, so to bootstrap from a beta, download install.sh from that release's page rather than from releases/latest.

install.sh kubernetes and install.sh docker never pick a beta on their own. A generated manifest outlives the run that wrote it, so if no stable release is available they stop and ask for -v VERSION or --prerelease rather than writing that tag into your cluster config.

Prerequisites¶

For the standard guided installation, you need:

a Linux ClickHouse host with sudo access
curl, plus sha256sum (usual on Linux) or shasum
an address for an OTLP/gRPC receiver, such as an OpenTelemetry Collector, Datadog Agent, or Grafana Alloy
access to ClickHouse through clickhouse-client or another command the installer can call

curl is required for release resolution, but install.sh does not preflight it yet. If release resolution reports a generic GitHub network or proxy error, confirm it with command -v curl.

Port 4317 is the standard OTLP/gRPC default, not a Click-Dog requirement. Use the port on which your receiver actually listens.

Most standard ClickHouse packages already define system.opentelemetry_span_log. The guided installer checks it and, when it is missing, offers to add the ClickHouse configuration and restart the server.

Choose your setup¶

One ClickHouse host¶

Use the standard guided installation. It installs one systemd service beside ClickHouse and is the easiest way to start.

More than one ClickHouse host¶

Use the Ansible guide to put one systemd sidecar on each ClickHouse host. It covers inventory, credentials, bounded concurrency, canary rollouts, updates, verification, and rollback.

Docker or Kubernetes¶

Use the self-contained Docker or Kubernetes guide. Those paths generate deployment files and do not install a systemd service on the machine where you run the generator.

Standard guided install¶

Run the quick-start command with no installer subcommand. The guide has three stages:

ClickHouse — detects the local connection, checks span logging, and sets up a dedicated click_dog_monitor user with SELECT on only system.opentelemetry_span_log and system.query_log. An existing user is never replaced, and its password changes only after explicit confirmation.
OTLP receiver — records the destination and checks that it is reachable.
Install — shows the files and settings it will create, then asks for confirmation before writing anything.

You can exit before the final confirmation without installing Click-Dog.

How `install.sh` works¶

install.sh is a bootstrap and host-lifecycle helper, not the monitoring service:

It resolves a release or accepts a pre-verified binary.
It verifies the release archive and stages the binary in a private temporary directory.
It runs the staged binary's own click-dog init renderer to produce the configuration. The shell script does not maintain a second YAML template.
It creates the dedicated runtime user, writes the config and password file, validates them with the staged binary, and creates the systemd unit.
It installs /usr/local/bin/click-dog, starts the service, and checks that systemd reports it active.

After that, systemd runs click-dog directly. install.sh is not copied into the service or needed for normal operation, so you may delete the downloaded script. All routine commands, including removal, are available from the installed click-dog binary. The current systemd update workflow is the one temporary exception; Updating explains why it still uses a freshly downloaded installer.

What gets installed¶

Component	Location
CLI and service binary	`/usr/local/bin/click-dog`
Configuration	`/etc/click-dog/click-dog.yaml`
ClickHouse password	`/etc/click-dog/.secret` (mode `0600`)
systemd unit	`/etc/systemd/system/click-dog.service`
Runtime identity	`click-dog` system user and group, with no login shell
Installer ownership record	`/var/lib/click-dog-installer/` (root-only; created only for identities the installer creates)
Logs	systemd journal (`journalctl -u click-dog`)

The generated production profile enables the circuit breaker, adaptive backoff, bounded ClickHouse connections, a deduplication cache, operation-noise filters, the Prometheus listener on :9090, and the health listener on :8686. The guided path detects whether the local ClickHouse endpoint uses TLS. See Configuration for every setting and Security and Privacy before sending production query telemetry.

Verify¶

The installed binary is on PATH, so commands are now run against click-dog, not through the installer. The standard config directory is private to the click-dog runtime identity because it contains credentials, so run commands that read it as that user. Start with the offline config check and then the end-to-end readiness check:

sudo -u click-dog click-dog validate --config /etc/click-dog/click-dog.yaml
sudo -u click-dog click-dog check --config /etc/click-dog/click-dog.yaml

validate parses the YAML without connecting to anything. check connects to ClickHouse and the configured exporters, checks the required grants and recent spans, and reports enrichment capabilities.

Test the exporter boundary and ClickHouse native tracing separately:

sudo -u click-dog click-dog test export --config /etc/click-dog/click-dog.yaml
sudo -u click-dog click-dog test tracing --config /etc/click-dog/click-dog.yaml

A PASS means the exporter accepted the batch; it does not prove the backend has indexed or displayed it yet.

Finally, inspect the service and its listeners:

click-dog deploy status
curl -s localhost:8686/status | jq
curl -s localhost:9090/metrics | head

See value¶

For Datadog, create the three packaged Application Query Analysis, Exported User Activity, and Click-Dog: Health dashboards:

DD_API_KEY=... DD_APP_KEY=... click-dog create-dashboards

For any backend, run a local read-only query analysis report:

sudo -u click-dog click-dog analyze queries --config /etc/click-dog/click-dog.yaml

The service is already running scheduled mode. It polls system.opentelemetry_span_log and exports qualifying traces to the configured backend. See Query Analysis for baselines and regression findings, and Operation Modes for backfill, dry-run, and flush.

Use `click-dog` from now on¶

Normal operation uses the installed CLI and standard system tools:

Task	Command
Show deployment and health state	`click-dog deploy status`
Validate config offline	`sudo -u click-dog click-dog validate --config /etc/click-dog/click-dog.yaml`
Check the data path	`sudo -u click-dog click-dog check --config /etc/click-dog/click-dog.yaml`
Trigger an immediate export cycle	`sudo -u click-dog click-dog flush --config /etc/click-dog/click-dog.yaml`
Follow logs	`journalctl -u click-dog -f`
Restart after a config change	`sudo systemctl restart click-dog`
Check for a release	`click-dog self-update --check`
Remove a standard systemd installation	`sudo click-dog deploy uninstall`

Use the dedicated Updating guide before changing the installed version. The current systemd update path performs an extra staged-config check before swapping the binary; the guide explains when to use it instead of the lighter self-update command.

Change or version-control the configuration¶

Edit /etc/click-dog/click-dog.yaml, validate it, then restart the service:

sudo vi /etc/click-dog/click-dog.yaml
sudo -u click-dog click-dog validate --config /etc/click-dog/click-dog.yaml
sudo systemctl restart click-dog

To start managing the config in version control, render it on a workstation and review the result before deployment:

click-dog init --wizard \
  --ch-user click_dog_monitor \
  --ch-password-file /etc/click-dog/.secret \
  -o click-dog.yaml

You can then deploy that YAML with your normal configuration management. The initial guided install does not create hidden state that prevents this transition.

Advanced single-host installation¶

The guided path is recommended for a first install. These options are useful for automation or an already-reviewed configuration.

Unattended install¶

Supply the ClickHouse password through the environment rather than a command line flag, where it would appear in process listings:

sudo env CLICKHOUSE_PASSWORD=... bash install.sh install \
  -c otel-collector.internal:4317 \
  --systemd

Unlike the guided path, the lower-level install command only creates the systemd unit when --systemd is present. Run it with sudo; it can otherwise complete prompts or downloads before failing at the first privileged write.

Bring your own YAML¶

Render and review the config on a workstation, then copy it to the target:

click-dog init --wizard \
  --ch-user click_dog_monitor \
  --ch-password-file /etc/click-dog/.secret \
  -o click-dog.yaml

scp click-dog.yaml HOST:/tmp/
ssh HOST 'curl -fsSL https://github.com/coltconsulting/click-dog/releases/latest/download/install.sh -o /tmp/install.sh && sudo CLICKHOUSE_PASSWORD=... bash /tmp/install.sh install -f /tmp/click-dog.yaml --systemd'

install -f uses your YAML instead of running click-dog init. It still writes the 0600 password file, validates the config, installs the binary, and creates the requested systemd unit. It does not provision the ClickHouse monitoring user; that user must already exist with matching credentials.

Do not use an inline ${CLICKHOUSE_PASSWORD} value with install -f --systemd. The generated unit has no EnvironmentFile=. Use password_file: /etc/click-dog/.secret, as shown above.

Do not use install as an update command

The non-interactive install path writes its destination config and secret before validation. If validation fails, it deletes both destination files; it does not restore files from an earlier non-interactive install. Use the systemd-only update flow in Updating for an existing service.

Useful single-host flags are:

Flag	Purpose
`-c ADDRESS`	Set the OTLP receiver address
`-f PATH`	Install a pre-rendered config
`-u USER`	Set the ClickHouse monitoring username
`-v VERSION`	Pin a release version
`-b BINARY`	Install a pre-verified local binary
`-k HOSTS`	Configure Keeper hosts for HA
`-C CMD`	Select the `clickhouse-client` command used by the guide
`-x PROXY`	Use an HTTPS proxy for downloads
`--systemd`	Create and enable the systemd unit on the unattended path
`--prerelease`	Resolve the newest public beta rather than the latest GA
`--dangerously-ignore-cosign`	Explicitly accept checksum-only verification

Run bash install.sh -h for the complete current flag reference.

Remove Click-Dog¶

Removal is available from the installed binary; the installer is not needed:

sudo click-dog deploy uninstall

The command shows the complete removal scope and asks for confirmation. It stops and disables the service, then removes the systemd unit, current and rollback binaries, config and credentials, log directory, and installer state. It removes the click-dog runtime user or group only when root-owned metadata proves that this installer created the same numeric identity. Pre-provisioned accounts and accounts from older installs without that proof are preserved. If the OS refuses to remove a proven runtime identity, the command reports the cause and exits nonzero, but still removes all managed Click-Dog files and preserves the identity for manual cleanup. It does not retain the binary or retry marker solely to repeat an account-management failure. Removing the installer state also removes its ownership proof, so later uninstaller runs do not retry that identity deletion. Use --yes only for already-reviewed automation. If managed-file cleanup or the systemd reload is interrupted or partially fails, run the same command again to resume it.

The uninstaller does not modify ClickHouse. The click_dog_monitor account and any config.d/opentelemetry.{xml,yaml} or users.d/click-dog-*.xml file you approved during the guided setup remain. Remove them through your ClickHouse administration workflow only after confirming that nothing else depends on them.

The command intentionally handles the standard systemd installation only. Remove Docker and Kubernetes deployments with their orchestrator, as described in their guides.

Other deployment guides¶

Ansible¶

Use Ansible for repeatable deployment to multiple ClickHouse hosts. It installs one local sidecar per inventory host and includes canary, bounded-concurrency, update, verification, and rollback workflows.

Kubernetes¶

Use Kubernetes for a centralized Deployment or a same-pod ClickHouse sidecar. The guide includes ClickHouse operator prerequisites, monitoring-user setup, manifest generation, topology, secrets, probes, updates, and verification.

Docker¶

Use Docker to generate a small Docker Compose deployment with its configuration and credentials kept outside the image.

Next steps¶

Configuration — full settings reference
Security and Privacy — choose the query-text posture before production
Updating — upgrades, config compatibility, and rollback
Operating Contract — delivery guarantees, topology, and capacity
Troubleshooting — diagnose missing spans and connectivity