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

macOS:

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

The Foundry Model

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.

pours/
└── deployment/
    ├── compose.yaml
    └── configs/
        ├── ingester/
        │   ├── ingester.yaml
        │   └── opamp.yaml
        ├── telemetrykeeper/
        │   └── keeper-0.yaml
        └── telemetrystore/
            ├── config.yaml
            └── functions.yaml

CLI reference

Usage:
  foundryctl [command]

Available Commands:
  gauge       Gauge whether required tools are available
  forge       Forge configuration and deployment files
  cast        Cast to the target environment
  gen         Generate example files for all supported deployments
  help        Help about any command

Flags:
  -d, --debug          Enable debug mode
  -f, --file string    Path to the Casting configuration file (default "casting.yaml")
  -p, --pours string   Directory for Pours (default "./pours")
  -h, --help           Help for foundryctl

gauge

Validates that all required tools are installed for your deployment mode:

foundryctl gauge -f casting.yaml

forge

Generates deployment and configuration files based on your Casting:

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

# Skip gauge check
foundryctl cast --no-gauge

# Skip forge (use existing Pours)
foundryctl cast --no-forge

gen

Generates example Casting configurations for all supported deployment modes:

foundryctl gen

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