Skip to content

Get started

This guide walks you through setting up your first ContainerHive project from scratch.

1. Install ContainerHive

Download the latest binary for your platform or use the Docker image. See Install ContainerHive for all options.

2. Set up BuildKit

ContainerHive uses BuildKit under the hood. Start a BuildKit daemon:

docker run -d --name buildkitd --privileged moby/buildkit:latest

3. Create your project

Create a hive.yml at the root of your project:

buildkit:
  address: tcp://127.0.0.1:8502

platforms:
  - linux/amd64
  - linux/arm64

For all configuration options, see Configure your project.

4. Define an image

Create an image directory with a definition and Dockerfile:

images/my-app/
├── image.yml
└── Dockerfile

image.yml:

tags:
  - name: 1.0.0
    versions:
      app: 1.0.0

versions:
  app: latest

Dockerfile:

FROM ubuntu:24.04
ARG APP_VERSION
RUN echo "Building version ${APP_VERSION}"

Versions defined in image.yml are automatically passed as Docker build arguments with a _VERSION suffix (app becomes APP_VERSION). See Write your Dockerfiles for details.

5. Add tests (optional)

Create a test.yml (or test.yml.gotpl if you need template variables) next to the Dockerfile:

schemaVersion: 2.0.0
commandTests:
  - name: "OS check"
    command: "cat"
    args: ["/etc/os-release"]
    expectedOutput: ["Ubuntu"]

See Define your tests for all test types and template usage.

6. Generate, build, and test

# Discover project and render configurations
ch generate

# Build images
ch build

# Run tests
ch test

7. Generate SBOMs (optional)

ch sbom

Generates CycloneDX JSON SBOMs for all built images. See How SBOM generation works.

8. Set up CI (optional)

Generate a CI pipeline for your provider:

ch template ci --provider github --output .github/workflows/build.yml
ch template ci --provider gitlab --output .gitlab-ci.yml

See Generate CI pipelines for all options.

Next steps