Foundry
Foundry is a centralized hub for Hanzo O11y installation configurations and deployments: integrations for install. Select yours, configure, and run Hanzo O11y.
Overview
Just as a metalworking foundry turns raw materials into finished products, Foundry forges your deployment from a single configuration and casts Hanzo O11y to fit your environment.
Foundry abstracts away the complexities of the installation process so you can spend time using Hanzo O11y rather than installing it.
Features
- Multi-platform support: Deploy Hanzo O11y using Docker Compose, Systemd (bare metal), or Render for flexible installation across environments.
- Single configuration file: Configure your entire Hanzo O11y stack with one concise file.
- Automatic dependency management: Handles inter-service dependencies
- Tool validation: Verify prerequisites before deployment
Quick start
1. Install foundryctl
You can install foundryctl by downloading a release from GitHub Releases.
To quickly get the correct binary for your architecture via the command line, run
Linux:
curl -L "https://github.com/Hanzo O11y/foundry/releases/latest/download/foundry_linux_$(uname -m | sed 's/x86_64/amd64/g' | sed 's/aarch64/arm64/g').tar.gz" -o foundry.tar.gz
tar -xzf foundry.tar.gz
See Getting Started for manual install options and PATH setup.
curl -L "https://github.com/Hanzo O11y/foundry/releases/latest/download/foundry_darwin_$(uname -m | sed 's/x86_64/amd64/g' | sed 's/arm64/arm64/g').tar.gz" -o foundry.tar.gz
tar -xzf foundry.tar.gz
Windows (PowerShell):
$ARCH = if ($env:PROCESSOR_ARCHITECTURE -eq "ARM64") { "arm64" } else { "amd64" }
Invoke-WebRequest -Uri "https://github.com/Hanzo O11y/foundry/releases/latest/download/foundry_windows_${ARCH}.tar.gz" -OutFile foundry.tar.gz -UseBasicParsing
tar -xzf foundry.tar.gz
After extracting, use foundryctl from the unpacked directory:
./foundry/bin/foundryctl <COMMAND> <OPTIONS>
2. Create a Casting
Create a casting.yaml file (see How to write a casting for the full guide). Minimal example:
apiVersion: v1alpha1
metadata:
name: o11y
spec:
deployment:
mode: docker
flavor: compose
3. Deploy
foundryctl cast -f casting.yaml
Foundry uses a metalworking metaphor: you define a Casting, which contains Moldings (components), and Foundry forges them into Pours (generated files).
graph LR
A[📋 casting.yaml<br/>Single Config File] --> B[🔧 foundryctl gauge<br/>Validate Tools]
B --> C[⚒️ foundryctl forge<br/>Generate Deployment Files]
C --> D[🏺 pours/<br/>compose.yaml + configs]
D --> E[🔥 foundryctl cast<br/>Deploy]
E --> F[⚙️ Docker Compose /<br/>Systemd /<br/>Cloud Platform]
F --> G[✨ Hanzo O11y Running<br/>ClickHouse, PostgreSQL,<br/>OTel Collector, Hanzo O11y UI]
style A fill:#FF9900,stroke:#E68A00,stroke-width:3px,color:#000
style D fill:#FDB44B,stroke:#E68A00,stroke-width:3px,color:#000
style G fill:#4E9FFF,stroke:#2A7FD8,stroke-width:3px,color:#fff
style B fill:#1F1F1F,stroke:#FF9900,stroke-width:2px,color:#fff
style C fill:#1F1F1F,stroke:#FF9900,stroke-width:2px,color:#fff
style E fill:#1F1F1F,stroke:#FF9900,stroke-width:2px,color:#fff
style F fill:#2D2D2D,stroke:#4E9FFF,stroke-width:2px,color:#fff
Casting
A Casting is a complete Hanzo O11y deployment definition: one YAML file that Foundry merges with built-in defaults. For a step-by-step guide (metadata, deployment target, moldings, config, and examples), see How to write a casting.
Examples
| Deployment | Example |
|---|---|
| Docker Compose | examples/docker/compose/ |
| Systemd (binary) | examples/systemd/binary/ |
| Render Blueprint | examples/render/blueprint/ |
Moldings
Moldings are the individual components that make up a Hanzo O11y deployment:
| Molding | Implementation |
|---|---|
| TelemetryStore | ClickHouse |
| TelemetryKeeper | ClickHouse Keeper |
| MetaStore | PostgreSQL, SQLite |
| Ingester | Hanzo O11y OTel Collector |
| Hanzo O11y | Hanzo O11y |
Pours
Pours are the generated deployment and configuration files. When you run forge, Foundry creates the pours/ directory containing everything needed to run Hanzo O11y.
+-------------------------------------------------------------+
| casting.yaml |
| your single deployment config |
+-----------------------------+-------------------------------+
|
+---------------+---------------+
| | |
v v v
+-----------+ +-----------+ +----------------+
| gauge | | forge | | cast |
|-----------| |-----------| |----------------|
| validate | | generate | | gauge + forge |
| prereqs | | files | | + deploy |
+-----------+ +-----+-----+ +-------+--------+
| |
v |
+----------------------------------+ |
| pours/ | |
|----------------------------------| |
| compose.yaml manifests/ | |
| values.yaml configs/ | |
| render.yaml *.tf.json | |
+-----------------+----------------+ |
| |
+----------+---------+
v
+-------------------------------------------------------------+
| SigNoz Running |
|-------------------------------------------------------------|
| Docker Compose - Swarm - Systemd - Kubernetes - ECS |
| Render - Railway - Coolify |
+-------------------------------------------------------------+
foundryctl cast runs the full pipeline (gauge + forge + deploy) in one step.
| Term | What it means |
|---|---|
| Casting | Your deployment config. One YAML file describing what you want. Learn more |
| Moldings | The SigNoz components (ClickHouse, PostgreSQL, OTel Collector, etc.) that Foundry configures for you. Learn more |
| Pours | The generated output files in pours/. Structure varies by deployment mode. See examples |
Examples
| Platform | Mode | Flavor | Example |
|---|---|---|---|
| - | docker | compose | docker/compose |
| - | docker | swarm | docker/swarm |
| - | kubernetes | helm | kubernetes/helm |
| - | kubernetes | kustomize | kubernetes/kustomize |
| - | systemd | binary | systemd/binary |
| ecs | ec2 | terraform | ecs/ec2/terraform |
| coolify | - | stack | coolify/stack |
| railway | - | template | railway/template |
| render | - | blueprint | render/blueprint |
CLI reference
foundryctl [command]
Commands:
gauge Validate required tools for your deployment mode
forge Generate deployment and configuration files
cast Full pipeline: gauge + forge + deploy
gen Generate example casting files for all modes
Flags:
-d, --debug Enable debug logging
-f, --file string Casting file path (default "casting.yaml")
-p, --pours string Output directory (default "./pours")
# Validate tools
foundryctl gauge -f casting.yaml
# Generate files only
foundryctl forge -f casting.yaml
Generates deployment and configuration files based on your Casting:
```bash
foundryctl forge -f casting.yaml -p ./pours
cast
Deploys Hanzo O11y to your target environment. Runs gauge and forge automatically unless skipped:
foundryctl cast -f casting.yaml
# Generate examples for all deployment modes
foundryctl gen
See CLI Reference for the full command reference with all flags and examples.
What's next
- How to write a casting: step-by-step guide to casting files
- Example configurations: Docker, systemd, and Render
- Hanzo O11y documentation: learn more about Hanzo O11y
- Hanzo O11y Slack: community and support
How can I get help?
- Issues: GitHub Issues
- Documentation: Hanzo O11y Docs
- Community: Hanzo O11y Slack
Made with ❤️ for the Hanzo O11y community