Container Images Reference

This reference documents Brokkr’s container images, repository locations, tag formats, and publishing commands.

Image Repositories

All Brokkr images are published to GitHub Container Registry (GHCR) under the colliery-io organization.

Available Images

Supported Architectures

All images support the following platforms:

• linux/amd64 - x86_64 architecture
• linux/arm64 - ARM64/aarch64 architecture

Tag Format Specifications

Semantic Version Tags

Created when a git tag matching v*.*.* is pushed.

Example: Tagging release v1.2.3 creates:

ghcr.io/colliery-io/brokkr-broker:1.2.3
ghcr.io/colliery-io/brokkr-broker:1.2
ghcr.io/colliery-io/brokkr-broker:1
ghcr.io/colliery-io/brokkr-broker:latest

Commit SHA Tags

Created for every commit that triggers a container build.

Example: Commit abc1234def5678 on the develop branch creates:

ghcr.io/colliery-io/brokkr-broker:develop-sha-abc1234

Branch Tags

Created for pushes to tracked branches.

Example: Push to develop branch creates:

ghcr.io/colliery-io/brokkr-broker:develop

Pull Request Tags

Optionally created for pull request builds.

Example: PR #123 creates:

ghcr.io/colliery-io/brokkr-broker:pr-123

Image Digests

Every image has a unique SHA256 digest that never changes:

ghcr.io/colliery-io/brokkr-broker@sha256:9fc91fae0f07c60ccbec61d86ff93fe825f92c42e5136295552ae196200dbe86

Production recommendation: Always use digest references for deployments to ensure immutability.

Building Images

Local Build (Single Architecture)

Build for your current platform:

angreal build multi-arch <component> --tag <tag>

Parameters:

• <component>: broker, agent, ui, or all
• --tag <tag>: Image tag (default: dev)
• --registry <url>: Registry URL (default: ghcr.io/colliery-io)
• --platforms <platforms>: Platform list (default: current platform for local builds)

Examples:

# Build broker for current platform
angreal build multi-arch broker --tag dev

# Build agent for specific platform
angreal build multi-arch agent --tag test --platforms linux/amd64

# Build all components
angreal build multi-arch all --tag v1.0.0

Publishing to Registry

Add --push to publish directly to the registry:

angreal build multi-arch <component> --tag <tag> --push

Important: When using --push, the build automatically targets both AMD64 and ARM64 unless --platforms is specified.

Examples:

# Push broker with multi-arch support
angreal build multi-arch broker --tag v1.0.0 --push

# Push all components
angreal build multi-arch all --tag v1.0.0 --push

# Push to custom registry
angreal build multi-arch broker --tag dev --registry myregistry.io/myorg --push

Pulling Images

Public Images

Images are publicly accessible and do not require authentication:

docker pull ghcr.io/colliery-io/brokkr-broker:v1.0.0

Using Specific Architectures

Docker automatically selects the appropriate architecture. To explicitly choose:

docker pull --platform linux/amd64 ghcr.io/colliery-io/brokkr-broker:v1.0.0
docker pull --platform linux/arm64 ghcr.io/colliery-io/brokkr-broker:v1.0.0

Using Digests

For immutable deployments:

docker pull ghcr.io/colliery-io/brokkr-broker@sha256:9fc91fae0f07c60ccbec61d86ff93fe825f92c42e5136295552ae196200dbe86

Authentication for Publishing

GitHub Personal Access Token

Required for manual publishing. Create a token with write:packages scope.

Set environment variable:

export GITHUB_TOKEN=ghp_yourtokenhere

Login to registry:

docker login ghcr.io -u <your-github-username> --password "$GITHUB_TOKEN"

GitHub Actions

Automated workflows use the built-in GITHUB_TOKEN secret with automatic permissions.

Inspecting Images

View Manifest

docker manifest inspect ghcr.io/colliery-io/brokkr-broker:v1.0.0

List Available Tags

Visit the package page:

https://github.com/orgs/colliery-io/packages/container/brokkr-broker

Check Image Architecture

docker image inspect ghcr.io/colliery-io/brokkr-broker:v1.0.0 | grep Architecture

Image Layer Structure

Brokkr images use multi-stage builds optimized for size and security.

Broker and Agent Images

1. Planner stage: Generates cargo-chef recipe
2. Cacher stage: Builds dependencies (cached layer)
3. Builder stage: Compiles Rust binaries
4. Final stage: Minimal Debian slim with runtime dependencies

UI Image

1. Single stage: Node.js Alpine (node:18-alpine) with npm install and application start

Kubernetes Deployment

Using Semantic Versions

apiVersion: apps/v1
kind: Deployment
metadata:
  name: brokkr-broker
spec:
  template:
    spec:
      containers:
      - name: broker
        image: ghcr.io/colliery-io/brokkr-broker:v1.2.3

Using Digests (Recommended)

apiVersion: apps/v1
kind: Deployment
metadata:
  name: brokkr-broker
spec:
  template:
    spec:
      containers:
      - name: broker
        image: ghcr.io/colliery-io/brokkr-broker@sha256:9fc91fae0f07c60ccbec61d86ff93fe825f92c42e5136295552ae196200dbe86

Image Size Reference

Approximate compressed image sizes:

Note: Sizes vary by release and dependency versions

Related Documentation

• Publishing Strategy - Understanding the tagging and distribution strategy