GREEN PACKAGE SKILL · VULTR · CLICKSTACK

ClickStack Package Skill

A reproducible Green workflow for the ClickHouse observability stack — ClickHouse, MongoDB, the HyperDX OpenTelemetry collector and UI — behind Caddy and Cloudflare on a guarded Vultr instance.

One host, both halves. Caddy proxies OTLP/HTTP on the standard /v1/{logs,traces,metrics} paths to the collector and serves the HyperDX UI on everything else, so an exporter needs only https://your-host. Every other port stays on loopback; the ingestion key is generated on the server and never leaves it.

Quick start

npx skills add getcolors/clickstack
cp .agents/skills/package-clickstack-green/green ./green
chmod +x green
./green build
./green create --dry-run

Build renders reproducible output and dry-run walks the workflow without provider side effects. Real creation and deletion require explicit authorization.

Architecture

Compute

One Vultr instance and a firewall opening 22, 80 and 443. In keygen mode the account SSH key resource is named after the profile and lives in this deployment's state.

DNS

One proxied Cloudflare A record for the configured host; Caddy obtains TLS from Let's Encrypt.

Server

Docker Compose: ClickHouse, MongoDB, the HyperDX collector, the HyperDX app, and Caddy — every image pinned by its own key in colors.yml.

Acceptance

Convergence proves ingestion end to end on the server; the workflow then checks the public UI and OTLP endpoint over HTTPS.

The machine keypair

The deployment owns its SSH key, following the workspace SSH Keypair Standard. Leave vultr-ssh-keys out of colors.yml and the first real create generates ~/.ssh/<profile>, registers it at Vultr under the profile name, and a successful delete removes it last — never before.

The key lives outside the checkout. Cloning a deployment repository does not carry machine access with it; copy ~/.ssh/<profile> deliberately. A key with no state is never overwritten, and a Vultr key named after the profile that this deployment's state does not own stops the run — if its fingerprint is not yours, do not delete it.

Supplying vultr-ssh-keys opts out entirely: the package then generates, validates and deletes no key material. Rotation is a rebuild, because Vultr key lists are ForceNew.

The SSH config block

Convergence also writes one ~/.ssh/config block, following the workspace SSH Config Standard, so ssh <profile> reaches the host with no address, user or -i flag. The block names an IdentityFile only in keygen mode, where the package knows the key because it generated it. It is inserted above the first Host line, because ssh_config takes the first value it obtains and a Host * stanza higher in the file would otherwise win on User and IdentityFile.

Delete removes the block before destroying the instance, the reverse of the keypair: a block that outlives its host is stale but harmless, while a key removed early locks you out of a machine that still exists.

Exposure

Port	Exposure	Purpose
22	`vultr-ssh-sources`	Key-only SSH for convergence and recovery
80 / 443	`vultr-http-sources`	Caddy: HyperDX UI and OTLP/HTTP ingestion
4317 / 4318 / 13133	loopback	Collector OTLP and health, reached through Caddy
8080 / 8000	loopback	HyperDX UI and API, reached through Caddy
8123	loopback	ClickHouse HTTP

Safety

Credentials are COLORS_PAR_* variables in the gitignored .envrc.private — never in colors.yml.
Never export COLORS_PAR_PROFILE; the profile keys remote state.
.colors/ is generated output: never edit or commit it.
compute-prevent-destroy: true guards deletion behind a one-run override.

Source on GitHub · Configuration reference · In the Package Skills Catalog · Featured on getcolors.ai