ClackHouse Stacks

stacks is the canonical catalog of local stack definitions consumed by the clackhouse CLI. It is a source repository for profile metadata, Compose assets, provisioning files, and stack-specific docs. It is not a user-facing CLI and it should not store rendered machine-local runtime state.

What lives here

• Canonical stack profiles under profiles/
• Machine-readable metadata.yaml contracts for CLI discovery and inspection
• Compose-based runtime templates and provisioning assets
• Validation schema, maintainer scripts, and CI workflows

What does not live here

• User-specific .env files
• Runtime data/ or logs/ directories
• Secrets
• Orchestration logic owned by the clackhouse CLI
• Agent/runtime behavior owned by other ClackHouse repos

Supported profiles

Profile	Status	Runner	Components
vm-grafana	canonical	docker-compose	VictoriaMetrics, Grafana

Additional profiles can land later, but the current catalog intentionally targets vm-grafana only.

Repository layout

stacks/
├── profiles/
│   └── vm-grafana/
├── schemas/
├── scripts/
├── .github/workflows/
├── CONTRIBUTING.md
└── README.md

Each profile is self-describing and must include:

• metadata.yaml
• README.md
• compose.yaml
• .env.example

Validation

Maintainer scripts live under scripts/:

• ./scripts/validate-profiles.sh checks profile contracts, required files, metadata consistency, and starter asset validity.
• ./scripts/lint-compose.sh renders each compose.yaml with docker compose config.
• ./scripts/render-example.sh copies a canonical profile into a temporary local runtime directory for smoke testing.
• ./scripts/install-git-hooks.sh installs the repo-local hook set.

Local commands are available through just:

just install-hooks
just check

GitHub Actions runs a single CI workflow that enforces the same validation and Compose lint policy on pushes and pull requests to main.

Versioned consumption

The long-term contract is for stacks to publish versioned tags or releases and for the clackhouse CLI to consume a known-compatible catalog version. The CLI should not depend on arbitrary live files from main at runtime.

Adding a profile

Follow CONTRIBUTING.md when introducing a new stack. Keep the contract boring, literal, and easy for the CLI to consume.