TazPod Image Hierarchy

TazPod images are built as a strict vertical stack. The point is not aesthetic layering; it is operational specialization. Each layer adds the tooling required for a broader scope of work without collapsing everything into one mutable image.

Actual Build Chain

The chain is defined by the Dockerfiles under .tazpod/:

  1. .tazpod/Dockerfile.base
  2. .tazpod/Dockerfile.aws
  3. .tazpod/Dockerfile.k8s
  4. .tazpod/Dockerfile.ai

Each Dockerfile uses the previously published image as its base.

Layer 1: tazpod-base

Defined in .tazpod/Dockerfile.base.

Adds:

  • Ubuntu 24.04 base OS
  • development tools: git, curl, build-essential, python3, golang-go, docker.io
  • shell/navigation tools: fzf, bat, fd, yq, tmux, eza, starship, zoxide
  • file/editor tools: nvim, yazi, lazygit
  • GitHub CLI: gh
  • networking tools: tailscale, wireguard-tools, dnsutils
  • Kaniko executor for in-environment image builds

It also:

  • creates the tazpod user (uid 1000)
  • injects the built tazpod binary into /home/tazpod/.local/bin/tazpod
  • installs Node.js LTS via NVM
  • copies dotfiles/ into the user home

This is the foundational shell image.

Layer 2: tazpod-aws

Defined in .tazpod/Dockerfile.aws.

Adds:

  • AWS CLI v2

Operational purpose:

  • AWS SSO login
  • S3 vault pull/push
  • bootstrap storage operations

Layer 3: tazpod-k8s

Defined in .tazpod/Dockerfile.k8s.

Adds:

  • kubectl
  • helm
  • k9s
  • talosctl
  • stern
  • kubectx, kubens
  • terraform
  • terragrunt
  • flux
  • ansible-core
  • google-cloud-cli
  • hcloud
  • oci-cli

Operational purpose:

  • cluster administration
  • Terraform/Terragrunt infrastructure work
  • Hetzner, GCP, and OCI control plane operations

Layer 4: tazpod-ai

Defined in .tazpod/Dockerfile.ai.

Adds:

  • @mariozechner/pi-coding-agent
  • @google/gemini-cli
  • opencode-ai
  • oh-my-pi
  • pi-extmgr
  • pi-mcp-adapter

Operational purpose:

  • AI-assisted terminal workflows
  • coding agents
  • semantic retrieval integrations
  • OpenCode and Gemini workflows

Why the Layering Matters

This split is not cosmetic. It lets CI/CD publish stable, reusable verticals while keeping dependency growth localized.

Examples:

  • an S3/bootstrap issue belongs to tazpod-aws
  • a Flux or Talos issue belongs to tazpod-k8s
  • an OpenCode or Gemini CLI issue belongs to tazpod-ai

It also explains why changes in CLI behavior or dotfiles can affect more than one published layer: the environment is intentionally a supply chain rather than one giant mutable image.

See Also