Skip to content

feat: optional slim image variant without docker-buildx#70

Open
Malith-Rukshan wants to merge 2 commits into
Finsys:mainfrom
Malith-Rukshan:feat/slim-image-variant
Open

feat: optional slim image variant without docker-buildx#70
Malith-Rukshan wants to merge 2 commits into
Finsys:mainfrom
Malith-Rukshan:feat/slim-image-variant

Conversation

@Malith-Rukshan

Copy link
Copy Markdown

Stacked on PR #69

What & why

The image is ~165 MB, of which the three Docker CLIs are the bulk:
docker-cli (~40 MB) + docker-compose (~29 MB) + docker-cli-buildx (~65 MB).
buildx is only needed when a stack actually builds an image on the host
(docker compose up --build / --no-cache). Plenty of agents only ever deploy
pre-built images and never need it.

This PR makes the buildx plugin optional via a build arg, so a much smaller
"slim" image can be published alongside the full one.

Changes

  • Dockerfile / Dockerfile.dev: add ARG INCLUDE_BUILDX=true; the
    docker-cli-buildx package is only added to the apko package list when
    INCLUDE_BUILDX=true.
  • .goreleaser.yml: also build & publish ghcr.io/finsys/hawser:<version>-slim
    and :latest-slim manifests (amd64 + arm64 built with
    --build-arg INCLUDE_BUILDX=false). armv7 is Alpine-based and never carried
    the buildx plugin, so the existing armv7 image is reused in the slim manifest.
  • Dockerfile.dev now installs the buildx plugin by default too, matching the
    release Dockerfile (it was previously missing it).
  • README.md: short note on the two variants.

Image sizes (local build, arm64)

Image Size
full (INCLUDE_BUILDX=true, default) ~164 MB
slim (INCLUDE_BUILDX=false) ~96 MB

Behaviour trade-off

The slim image can deploy, pull, and manage compose stacks (up, down,
pull, ps, logs, restart, stop, start), and all Docker-API proxy
features work normally. It cannot build images on the host — i.e. a stack
that has build: directives (or the Dockhand "Build images" / "No build cache"
options) will fail on the slim image. Use the full :latest image on hosts that
build stacks from source; use :latest-slim on hosts that only run pre-built
registry images. Default tags (:latest, :<version>) are unchanged.

Testing

  • docker build (full) → buildx present, healthcheck reports healthy.
  • docker build --build-arg INCLUDE_BUILDX=falsedocker buildx absent,
    docker/docker compose work, image ~96 MB.
  • Same checks against Dockerfile.dev (both variants).
  • Built for linux/amd64, pushed to a private registry, and run against a live
    Dockhand instance in both Edge and Standard modes — agent connects, metrics
    flow, and all non-build compose operations behave identically to the current
    image.

Notes for reviewers

  • This is intentionally conservative: no changes to the default image contents,
    no new runtime deps, the slim variant is purely additive (extra tags).
  • If you'd rather the slim agent return a clearer "buildx not available" error to
    Dockhand when a build is requested (instead of surfacing compose's own
    message), happy to add that — let me know.

The container HEALTHCHECK previously shelled out to wget. Add a small
"hawser healthcheck" subcommand that probes /_hawser/health (auto-detecting
TLS via TLS_CERT, like the old shell command) and switch the HEALTHCHECK to
use it. This removes the wget package from the image.

The /_hawser/health HTTP endpoint is unchanged.

Also use COPY --chmod instead of a separate RUN chmod for the binary.
Add an INCLUDE_BUILDX build arg to Dockerfile / Dockerfile.dev. With
INCLUDE_BUILDX=false the docker-cli-buildx package (~65 MB) is omitted,
producing a slim image (~95 MB vs ~165 MB) that can deploy and manage compose
stacks but cannot build images on the host (docker compose up --build).

GoReleaser now also publishes :<version>-slim / :latest-slim manifests.
Dockerfile.dev gains the buildx plugin by default to match Dockerfile.
@Malith-Rukshan Malith-Rukshan force-pushed the feat/slim-image-variant branch from c69d2fb to 4f824a6 Compare June 4, 2026 19:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant