SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillspackage-clickstack-blue

package-clickstack-blue

Deployment & operations

View repository

Updated 10-16 02:38

About this skill

ClickStack with Blue

Operate one ClickStack deployment from non-secret colors.yml. Read references/configuration.md before changing configuration or running a lifecycle operation.

One public host serves both halves of the stack: Caddy terminates TLS, proxies OTLP/HTTP on /v1/{logs,traces,metrics} to the collector, and serves the HyperDX UI on everything else. Point an OTLP exporter at https://<clickstack-host> with the server-generated ingestion key as its authorization header.

Compute ownership

The pinned colors-compute library owns provider selection, remote S3/R2 state, deployment coordination, machine keys, network policy and the single node. This package supplies singleton topology and SSH/HTTP ingress, then uses the returned address, login user and SSH identity for its application steps. New provider support belongs in the library; consumers update its pin. The application needs a supported Ubuntu image and sufficient memory for ClickHouse, MongoDB and HyperDX. Build first to check adapter capabilities.

Use clickstack-ssh-sources and clickstack-http-sources for neutral CIDR allowlists. Existing selected-provider source options remain compatible. External account key references may use ssh-private-key-path or operator/agent SSH configuration; external private keys are never generated or removed. The local SSH block writes IdentityFile only for a managed deployment key.

Existing <profile>/clickstack-infrastructure.tfstate is refused before compute mutation. Do not remove it to bypass this check: migrate ownership explicitly or destroy the old deployment through its original version first. Unreadable state and provider mismatches fail closed.

Safety

  • Keep credentials in gitignored .envrc.private as COLORS_PAR_* variables.
  • Never set COLORS_PAR_PROFILE or edit/commit .colors/.
  • Keep compute-prevent-destroy: true; deletion requires separate explicit authorization and a one-run environment override.
  • Build and dry-run before a real create.
  • Only Caddy 80/443 and key-only SSH are public; the admin password and the ingestion key are generated on the server and never leave it.
./blue build
./blue create --dry-run
./blue create

The machine keypair

The deployment owns its SSH key per the workspace SSH Keypair Standard. With no vultr-ssh-keys (or digitalocean-ssh-keys) in colors.yml, the first real create generates ~/.ssh/<profile>, registers it at the provider under the profile name, and a successful delete removes it last.

The key lives outside the checkout, so cloning the deployment repository elsewhere does not carry access — copy ~/.ssh/<profile>(.pub) deliberately. A key with no state, or a provider key named after the profile that this deployment's state does not own, stops the run: verify at the provider before removing anything, and never delete a key whose fingerprint is not yours. Rotation is a rebuild. Supplying <provider>-ssh-keys opts out and the package then touches no key material.

Convergence creates the initial HyperDX team named by clickstack-admin-email. This is required, not cosmetic: HyperDX configures the collector over OpAMP and sends nothing until a team exists, so before that the collector binds no OTLP receivers at all. The ingestion key is that team's, written to /etc/clickstack/ingestion.env. Convergence also writes a ~/.ssh/config block, so reading it and the generated admin password needs no address:

ssh <profile> 'cat /etc/clickstack/admin.env'
ssh <profile> 'cat /etc/clickstack/ingestion.env'

A real create ends with public HTTPS acceptance checks on the UI and the OTLP endpoint; the end-to-end ingest proof — one OTLP record through the collector into ClickHouse — runs on the server during convergence.