Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 2 additions & 12 deletions .github/workflows/images.yml
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,6 @@ on:
- '.github/workflows/images.yml'
tags:
- 'images/base/v*'
- 'images/systemd/v*'
- 'images/dind/v*'

env:
REGISTRY: ghcr.io
Expand All @@ -28,8 +26,6 @@ jobs:
matrix:
dockerfile:
- images/base/Dockerfile
- images/systemd/Dockerfile
- images/dind/Dockerfile
steps:
- name: Checkout repository
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
Expand Down Expand Up @@ -61,7 +57,7 @@ jobs:
echo "Building $VARIANT with version $VERSION"
else
# Build all variants on push to master or PR
echo 'variants=["base", "systemd", "dind"]' >> $GITHUB_OUTPUT
echo 'variants=["base"]' >> $GITHUB_OUTPUT
echo "is_release=false" >> $GITHUB_OUTPUT
echo "version=latest" >> $GITHUB_OUTPUT
echo "Building all variants with latest tag"
Expand All @@ -80,8 +76,6 @@ jobs:
variant: ${{ fromJson(needs.prepare.outputs.variants) }}
outputs:
base-digest: ${{ steps.digest.outputs.base }}
systemd-digest: ${{ steps.digest.outputs.systemd }}
dind-digest: ${{ steps.digest.outputs.dind }}

steps:
- name: Checkout repository
Expand Down Expand Up @@ -146,11 +140,7 @@ jobs:
id: digest
run: |
# Get the digest from the build job output
case "${{ matrix.variant }}" in
base) echo "value=${{ needs.build.outputs.base-digest }}" >> $GITHUB_OUTPUT ;;
systemd) echo "value=${{ needs.build.outputs.systemd-digest }}" >> $GITHUB_OUTPUT ;;
dind) echo "value=${{ needs.build.outputs.dind-digest }}" >> $GITHUB_OUTPUT ;;
esac
echo "value=${{ needs.build.outputs.base-digest }}" >> $GITHUB_OUTPUT

- name: Log in to Container Registry
uses: docker/login-action@74a5d142397b4f367a81961eba4e8cd7edddf772 # v3
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/security-scan.yml
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ jobs:
strategy:
fail-fast: false
matrix:
variant: [base, systemd, dind]
variant: [base]

steps:
- name: Checkout repository
Expand Down
4 changes: 1 addition & 3 deletions .release-please-manifest.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,4 @@
{
".": "0.0.0",
"images/base": "0.0.0",
"images/systemd": "0.0.0",
"images/dind": "0.0.0"
"images/base": "0.0.0"
}
25 changes: 7 additions & 18 deletions RELEASE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,12 @@ This document describes the release process for Headjack, covering the CLI and c

## Overview

Headjack uses [release-please](https://github.com/googleapis/release-please) to automate releases. The system manages four independent components:
Headjack uses [release-please](https://github.com/googleapis/release-please) to automate releases. The system manages two independent components:

| Component | Tag Format | Changelog |
|-----------|------------|-----------|
| CLI | `v1.0.0` | `CHANGELOG.md` |
| base image | `images/base/v1.0.0` | `images/base/CHANGELOG.md` |
| systemd image | `images/systemd/v1.0.0` | `images/systemd/CHANGELOG.md` |
| dind image | `images/dind/v1.0.0` | `images/dind/CHANGELOG.md` |

## Release Flow

Expand Down Expand Up @@ -101,7 +99,6 @@ git commit -m "feat: add instance list command"

# Image changes (touches files in images/)
git commit -m "feat(images/base): add ripgrep to base image"
git commit -m "fix(images/dind): update Docker CE version"
```

## CLI Releases
Expand Down Expand Up @@ -146,21 +143,19 @@ Triggers on `v*` tags and runs GoReleaser with:

Container images are built and published when `images/*/v*` tags are pushed.

### Image Variants
### Image Variant

| Variant | Base | Features |
|---------|------|----------|
| `base` | Ubuntu 24.04 | Dev tools, agent CLIs, version managers |
| `systemd` | `base` | systemd init system |
| `dind` | `systemd` | Docker-in-Docker support |

### Image Tags

Each release creates two tags:

```
ghcr.io/gilmanlab/headjack:base # Latest
ghcr.io/gilmanlab/headjack:base-v1.0.0 # Versioned
ghcr.io/gilmanlab/headjack:base # Latest
ghcr.io/gilmanlab/headjack:base-v1.0.0 # Versioned
```

### Build Features
Expand All @@ -174,8 +169,6 @@ ghcr.io/gilmanlab/headjack:base-v1.0.0 # Versioned

Triggers on:
- `images/base/v*` tags
- `images/systemd/v*` tags
- `images/dind/v*` tags

Jobs:
1. **lint**: Validates Dockerfiles with hadolint
Expand All @@ -194,9 +187,7 @@ Defines components, release types, and changelog configuration:
"separate-pull-requests": true,
"packages": {
".": { "component": "cli", "include-component-in-tag": false },
"images/base": { "component": "images/base", "include-component-in-tag": true },
"images/systemd": { "component": "images/systemd", "include-component-in-tag": true },
"images/dind": { "component": "images/dind", "include-component-in-tag": true }
"images/base": { "component": "images/base", "include-component-in-tag": true }
}
}
```
Expand All @@ -208,9 +199,7 @@ Tracks current versions for each component:
```json
{
".": "1.0.0",
"images/base": "1.0.0",
"images/systemd": "1.0.0",
"images/dind": "1.0.0"
"images/base": "1.0.0"
}
```

Expand Down Expand Up @@ -273,7 +262,7 @@ cosign verify-attestation ghcr.io/gilmanlab/headjack:base \

Release-please uses file paths to attribute commits. Ensure your changes are in the correct directory:
- CLI: Root Go files (`*.go`, `internal/`, `cmd/`)
- Images: `images/base/`, `images/systemd/`, `images/dind/`
- Images: `images/base/`

### Release PR Has Wrong Version

Expand Down
25 changes: 2 additions & 23 deletions docker-bake.hcl
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,7 @@
# docker buildx bake base # Build only base image
# docker buildx bake --push # Build and push all images
#
# The images have dependencies: base -> systemd -> dind
# Bake automatically builds dependencies first.
# The base image provides all required functionality.

variable "REGISTRY" {
default = "ghcr.io"
Expand All @@ -22,7 +21,7 @@ variable "TAG" {

# Target group to build all images
group "default" {
targets = ["base", "systemd", "dind"]
targets = ["base"]
}

target "base" {
Expand All @@ -31,23 +30,3 @@ target "base" {
tags = ["${REGISTRY}/${REPOSITORY}:base", "${REGISTRY}/${REPOSITORY}:base-${TAG}"]
platforms = ["linux/amd64", "linux/arm64"]
}

target "systemd" {
context = "images/systemd"
dockerfile = "Dockerfile"
tags = ["${REGISTRY}/${REPOSITORY}:systemd", "${REGISTRY}/${REPOSITORY}:systemd-${TAG}"]
platforms = ["linux/amd64", "linux/arm64"]
contexts = {
base = "target:base"
}
}

target "dind" {
context = "images/dind"
dockerfile = "Dockerfile"
tags = ["${REGISTRY}/${REPOSITORY}:dind", "${REGISTRY}/${REPOSITORY}:dind-${TAG}"]
platforms = ["linux/amd64", "linux/arm64"]
contexts = {
systemd = "target:systemd"
}
}
2 changes: 1 addition & 1 deletion docs/docs/reference/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ Default values applied when creating new instances.
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `default.agent` | string | `""` (empty) | Default agent to use. Valid values: `claude`, `gemini`, `codex`. Empty means no default. |
| `default.base_image` | string | `ghcr.io/gilmanlab/headjack:base` | Container image to use for instances. Available variants: `:base` (minimal), `:systemd` (with init), `:dind` (with Docker). |
| `default.base_image` | string | `ghcr.io/gilmanlab/headjack:base` | Container image to use for instances. |

### agents

Expand Down
85 changes: 20 additions & 65 deletions docs/docs/reference/images/overview.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,16 @@
---
sidebar_position: 1
title: Overview
description: Headjack container image variants
description: Headjack container image
---

# Container Images Overview
# Container Image Overview

Headjack provides pre-built container images for running isolated CLI-based LLM coding agents. All images are based on Ubuntu 24.04 LTS and include development tools, agent CLIs, and language runtime managers.
Headjack provides a pre-built container image for running isolated CLI-based LLM coding agents. The image is based on Ubuntu 24.04 LTS and includes development tools, agent CLIs, and language runtime managers.

## Registry

All images are published to the GitHub Container Registry:
The image is published to the GitHub Container Registry:

```
ghcr.io/gilmanlab/headjack
Expand All @@ -21,79 +21,36 @@ ghcr.io/gilmanlab/headjack
Images follow a consistent naming pattern:

```
ghcr.io/gilmanlab/headjack:<variant>
ghcr.io/gilmanlab/headjack:<variant>-<version>
ghcr.io/gilmanlab/headjack:base
ghcr.io/gilmanlab/headjack:base-<version>
```

Examples:
- `ghcr.io/gilmanlab/headjack:base` - Latest base image
- `ghcr.io/gilmanlab/headjack:base-v1.0.0` - Base image version 1.0.0
- `ghcr.io/gilmanlab/headjack:dind` - Latest Docker-in-Docker image

## Image Variants
## Features

The images form an inheritance hierarchy. Each variant builds on the previous one:
The base image includes:

```
base --> systemd --> dind
```

### Comparison Table

| Feature | base | systemd | dind |
|---------|------|---------|------|
| Ubuntu 24.04 LTS | Yes | Yes | Yes |
| Agent CLIs (Claude, Gemini, Codex) | Yes | Yes | Yes |
| Version managers (pyenv, nodenv, goenv, rustup) | Yes | Yes | Yes |
| Development tools (git, gh, vim, ripgrep, etc.) | Yes | Yes | Yes |
| Terminal multiplexer (tmux) | Yes | Yes | Yes |
| systemd init system | No | Yes | Yes |
| Docker CE | No | No | Yes |
| Docker Compose plugin | No | No | Yes |
| Docker Buildx plugin | No | No | Yes |
| Multi-architecture support (amd64, arm64) | Yes | Yes | Yes |

### Image Sizes

| Variant | Approximate Size |
|---------|-----------------|
| `base` | ~600 MB |
| `systemd` | ~620 MB |
| `dind` | ~1.0 GB |
| Feature | Included |
|---------|----------|
| Ubuntu 24.04 LTS | Yes |
| Agent CLIs (Claude, Gemini, Codex) | Yes |
| Version managers (pyenv, nodenv, goenv, rustup) | Yes |
| Development tools (git, gh, vim, ripgrep, etc.) | Yes |
| Terminal multiplexer (tmux) | Yes |
| Multi-architecture support (amd64, arm64) | Yes |

## Choosing an Image

### Use `base` when:
- Running simple agent workflows that do not require background services
- Minimizing image size is a priority
- No systemd or Docker functionality is needed

### Use `systemd` when:
- Your workflow requires running background services managed by systemd
- You need a proper init system for signal handling and process management
- You are running services that expect systemd to be available

### Use `dind` when:
- Your workflow requires building or running Docker containers
- You need to test containerized applications
- Your agent needs to execute Docker commands (e.g., `docker build`, `docker compose`)

## Pulling Images
## Pulling the Image

```bash
# Pull the base image
docker pull ghcr.io/gilmanlab/headjack:base

# Pull the systemd image
docker pull ghcr.io/gilmanlab/headjack:systemd

# Pull the Docker-in-Docker image
docker pull ghcr.io/gilmanlab/headjack:dind
```

## Security

All images are:
The image is:
- **Signed** with Cosign using keyless signing (Sigstore)
- **Attested** with SBOM (Software Bill of Materials) in SPDX format
- **Scanned** for vulnerabilities using Trivy
Expand All @@ -106,10 +63,8 @@ cosign verify ghcr.io/gilmanlab/headjack:base \
--certificate-oidc-issuer='https://token.actions.githubusercontent.com'
```

## Dockerfiles
## Dockerfile

For complete image specifications, see the Dockerfiles in the repository:
For the complete image specification, see the Dockerfile in the repository:

- [Base Dockerfile](https://github.com/GilmanLab/headjack/blob/master/images/base/Dockerfile)
- [Systemd Dockerfile](https://github.com/GilmanLab/headjack/blob/master/images/systemd/Dockerfile)
- [Docker-in-Docker Dockerfile](https://github.com/GilmanLab/headjack/blob/master/images/dind/Dockerfile)
23 changes: 0 additions & 23 deletions images/dind/.trivyignore

This file was deleted.

3 changes: 0 additions & 3 deletions images/dind/CHANGELOG.md

This file was deleted.

Loading
Loading