eblume/blumeops
1
1
Fork 0
Code Issues Pull requests Projects Releases 83 Packages Wiki Activity Actions
blumeops/docs/how-to/deployment/build-container-image.md
Erich Blume ffa8727660 Adopt commit-based container tags (#232) 
## Summary
- Replace git-tag-triggered container builds with path-based triggers on main and workflow_dispatch
- Image tags now encode upstream app version + commit SHA (`vX.Y.Z-<sha>`) for full traceability
- Replace `container-tag-and-release` task with `container-build-and-release` (dispatches workflows via Forgejo API)
- Update dagger `publish()` to accept `commit_sha` parameter
- Update all docs and references to the new workflow

## Deployment and Testing
- [ ] Merge to main
- [ ] `mise run container-build-and-release <name>` for each container to populate new-format tags
- [ ] Verify tags in registry via `mise run container-list`
- [ ] Existing images untouched — old tags remain available

Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/232
2026-02-20 22:56:20 -08:00

4.3 KiB
Raw Blame History

title modified last-reviewed tags
Build Container Image 2026-02-20 2026-02-15
how-to
containers
ci

Build a Container Image

How to create a custom container image in BlumeOps, build it locally, and release it to the zot registry via the Forgejo CI pipeline.

Prerequisites

  • Dagger CLI installed locally (for Dockerfile builds)
  • A Dockerfile and/or default.nix for the service

1. Create the container directory

Add build files under containers/<name>/:

containers/<name>/
├── Dockerfile      (built by Dagger on the k8s runner)
├── default.nix     (built by nix-build on the ringtail runner)
└── (optional scripts, configs)

A container can have one or both build files. The directory name becomes the image name: registry.ops.eblu.me/blumeops/<name>.

2. Build locally

Dockerfile — test with Dagger:

dagger call build --src=. --container-name=<name>

Nix — test with Dagger (no local nix required):

dagger call build-nix --src=. --container-name=<name> export --path=./<name>.tar.gz

Or with nix-build directly (requires nix, e.g. on ringtail):

nix-build containers/<name>/default.nix -o result

3. Release

Container builds trigger automatically when changes to containers/<name>/ are merged to main. Both workflows fire and each skips if the relevant build file is absent.

To trigger a manual build (e.g. from a branch or to rebuild at a specific commit):

mise run container-build-and-release <name>
mise run container-build-and-release <name> --ref <commit-sha>

Use --dry-run to preview without dispatching.

Build file Workflow Runner Registry tag
Dockerfile build-container.yaml k8s (indri) :vX.Y.Z-<sha>
default.nix build-container-nix.yaml nix-container-builder (ringtail) :vX.Y.Z-<sha>-nix

The version (X.Y.Z) is extracted from ARG CONTAINER_APP_VERSION= in the Dockerfile or version = "..." in default.nix. The SHA is the short (7-char) commit hash.

Check available images and tags with:

mise run container-list

4. Update k8s manifests

Change the image reference in argocd/manifests/<service>/deployment.yaml:

image: registry.ops.eblu.me/blumeops/<name>:vX.Y.Z-abc1234

Then deploy per deploy-k8s-service.

Common Patterns

Existing containers demonstrate several build approaches:

Pattern Example Notes
Alpine package install #transmission Simplest — install from apk
Go from source #miniflux Clone upstream, go build
Multi-stage with Node + Go #navidrome Separate UI and backend build stages
Multi-stage Elixir #teslamate Elixir release with Node assets
Runtime tarball download #kiwix-serve Download pre-built binary with arch detection
Nix dockerTools #nettest-nix buildLayeredImage with nixpkgs tools

transmission

containers/transmission/Dockerfile — Installs transmission-daemon directly from Alpine packages. Good starting point for services available in apk.

miniflux

containers/miniflux/Dockerfile — Two-stage Go build. Clones upstream at a pinned version tag, runs make, copies the binary into a minimal Alpine runtime.

navidrome

containers/navidrome/Dockerfile — Three-stage build with separate Node.js UI compilation, Go backend build with CGO (taglib), and a minimal Alpine runtime with ffmpeg.

teslamate

containers/teslamate/Dockerfile — Two-stage Elixir build with Node.js asset compilation. Uses Debian-based images due to Elixir/OTP dependencies.

kiwix-serve

containers/kiwix-serve/Dockerfile — Downloads a pre-built binary from upstream, with architecture detection for cross-platform support.

nettest (nix)

containers/nettest/default.nix — Uses dockerTools.buildLayeredImage with buildEnv to merge nixpkgs tools (curl, jq, dnsutils, bash). Runs alongside the existing Dockerfile; the nix variant is tagged :version-nix in the registry.

Related