GREEN PACKAGE SKILL · CLICKHOUSE · KEEPER · METABASE

clickhouse

Provision a private replicated ClickHouse data platform on Hetzner with Keeper, Metabase, WireGuard-only service access, and a local dbt project.

Three replicas
Three Keeper members
WireGuard only
Metabase + dbt

#Introduction

This package creates three ClickHouse/Keeper nodes and one Metabase host on a shared private Hetzner network. Cloudflare publishes DNS-only private VPN addresses, and a generated WireGuard client provides operator access.

Safe first stepsbuild renders local files and create --dry-run prints the workflow without contacting providers. Review both before approving a real operation.

#Quick start

npx skills add getcolors/clickhouse
cp .agents/skills/package-clickhouse-green/green ./green
./green build
./green create --dry-run
# after approval:
./green create

#Topology and workflow

network + managed SSH
  ├─ node 1 ─┐
  ├─ node 2 ─┼─ ClickHouse + Keeper (one shard, three replicas)
  ├─ node 3 ─┘
  └─ metabase ─ PostgreSQL metadata + Metabase

shared firewall + DNS + WireGuard + local dbt acceptance

Server provisioning runs concurrently after shared infrastructure; ClickHouse and Metabase convergence also run concurrently. A successful create finishes with acceptance and zero-change OpenTofu plans.

#Desired state

Area	Important choices
Topology	Fixed one shard, three replicas, three Keeper members
Compute	Hetzner node and Metabase sizes, image, location, SSH keys
Network	Private subnet, WireGuard network and client
Software	Pinned ClickHouse, Keeper, Metabase, PostgreSQL, and dbt inputs
DNS	Domain used to derive ClickHouse node and Metabase names
State	Local, S3, or R2 backend

See the configuration reference.

#Private networking

Public ingress is limited to SSH and WireGuard UDP. ClickHouse, Keeper, PostgreSQL, and Metabase ports remain closed publicly. DNS records are unproxied and point at WireGuard addresses, so names resolve publicly but services remain reachable only through the VPN.

#Services and clients

Each data node runs ClickHouse and Keeper with replication credentials and an interserver secret supplied at converge time. Metabase stores its own metadata in PostgreSQL and connects to ClickHouse over the private network. The package renders a local dbt sample project for acceptance and exploration.

#Command reference

Command	Effect
`./green build`	Render all stages
`./green create --dry-run`	Print the graph
`./green create`	Provision, converge, and accept
`./green delete`	Guarded destruction of all four hosts and shared infrastructure

#State and generated material

Remote keys are <profile>/<stage>.tfstate across network, managed SSH, four servers, firewall, DNS, and related stages. Generated output includes retained local SSH/WireGuard private state and dbt state.

Generated output is sensitiveNever read it as source, edit it, publish it, or commit it.

#Credentials and safety

Provider, ClickHouse user, interserver, Metabase, and database credentials all use COLORS_PAR_*. The Metabase encryption key must be at least 16 characters and remain stable.

Never export COLORS_PAR_PROFILE.
Keep compute-prevent-destroy: true.
Never expose database or dashboard ports publicly.

#Troubleshooting

A DNS name resolves but the service does not connect

That is expected without WireGuard. Confirm the client tunnel and route before checking the service.

Replication is unhealthy

Check Keeper quorum first, then private node reachability and the stable interserver secret.