Publish UBI as a container image

[polarathene]

This would be for convenience of using UBI without extra steps to acquire a version that matches the platform and extract it.

A PR was raised for just that implements this post-release by having a simple Dockerfile the official project manages that copies the appropriate GH release artifact. It should be possible to adapt that PR to the ubi repo here.

---

ubi/.github/workflows/ci.yml

Lines 1 to 9 in e061108

	name: Tests and release
	on:
	push:
	branches:
	- "**"
	tags-ignore:
	- "ubi-*"
	pull_request:

ubi/.github/workflows/ci.yml

Lines 147 to 153 in e061108

	- name: Publish artifacts and release
	uses: houseabsolute/actions-rust-release@v0
	with:
	executable-name: ubi
	target: ${{ matrix.platform.target }}
	action-gh-release-parameters: '{ "make_latest": false }'
	if: matrix.toolchain == 'stable' && matrix.platform.features == ''

That last step calls out to your own maintained release action that at the end publishes to GH Releases if the conditions such as a release tag are met.

After that action is done publishing a new release with the UBI binaries, a workflow can be triggered via on.release like below.

Reference workflow and Dockerfile

NOTE: I'm a bit busy atm, this example might need a bit more revision but should mostly be viable. I'll open a PR once I have time to spare (hopefully in next day or so).

name: 'Build and Publish the container image'

on:
  release:
    types:
      - published

  # Manual trigger via GH Actions page (runs this workflow from a selected tag or branch),
  # NOTE: Affects the value `github.ref_type` (`branch` or `tag`) + commit cloned for `Dockerfile` source.
  workflow_dispatch:
    inputs:
      # Optional input to override tag
      tag:
        description: 'Release tag of UBI (to include in image + influences image tag)'
        required: false
        type: string

env:
  RELEASE_VERSION: ${{ inputs.tag || github.ref_name }}

jobs:
  container:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - name: Prepare image metadata
        id: metadata
        uses: docker/metadata-action@v5
        env:
          DOCKER_METADATA_ANNOTATIONS_LEVELS: index
        with:
          images: |
            ghcr.io/${{ github.repository }}
          # NOTE: The `semver` tag type below (with the default `flavor.latest=auto` action setting),
          # will implicitly append a `latest` tag to publish:
          # https://github.com/docker/metadata-action/issues/567#issuecomment-3579068205
          # https://github.com/docker/metadata-action/issues/461#issuecomment-2680849083
          tags: |
            type=semver,pattern={{major}}.{{minor}}.{{patch}},value=${{ env.RELEASE_VERSION }}
            type=semver,pattern={{major}}.{{minor}},value=${{ env.RELEASE_VERSION }}
            # NOTE: `enable` condition required until no longer tagging major-zero versions:
            type=semver,pattern={{major}},value=${{ env.RELEASE_VERSION }},enable=${{ !startsWith(github.ref, 'refs/tags/v0.') }}

          # Override defaults from `docker/metadata-action`:
          # https://github.com/docker/metadata-action/issues/592
          annotations: |
            org.opencontainers.image.created={{ commit_date 'YYYY-MM-DDTHH:mm:ss.SSS[Z]' }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Log in to Container Registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.repository_owner }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and push container image
        uses: docker/build-push-action@v6
        env:
          SOURCE_DATE_EPOCH: 0
        with:
          provenance: false
          push: true
          platforms: linux/amd64,linux/arm64
          tags: ${{ steps.metadata.outputs.tags }}
          annotations: ${{ steps.metadata.outputs.annotations }}
          outputs: type=image,oci-mediatypes=true,oci-artifact=true,rewrite-timestamp=true
          build-args: |
            RELEASE_TAG=${{ env.RELEASE_VERSION }}

Dockerfile:

# syntax=docker/dockerfile:1

# NOTE: ARGs `BUILDPLATFORM` + `TARGETARCH` are implicitly defined by BuildKit:
# https://docs.docker.com/reference/dockerfile/#automatic-platform-args-in-the-global-scope
# NOTE: BuildKit supplied ARGs use convention amd64 / arm64 (instead of the mixed arch convention used by UBI)
# https://itsfoss.com/arm-aarch64-x86_64
#
# Map arch naming conventions from BuildKit to UBI convention (TARGETARCH => UBI_ARCH):
FROM --platform=${BUILDPLATFORM} alpine AS downloader-amd64
ARG UBI_ARCH=x86_64
FROM --platform=${BUILDPLATFORM} alpine AS downloader-arm64
ARG UBI_ARCH=arm64


# Fetch the expected version of `ubi` via GH Releases:
FROM downloader-${TARGETARCH} AS downloader
SHELL ["/bin/ash", "-eux", "-o", "pipefail", "-c"]
# This ARG will be set via GitHub Actions during release builds
ARG RELEASE_TAG
ARG RELEASE_URL="https://github.com/houseabsolute/ubi/releases/download/${RELEASE_TAG}/ubi-Linux-musl-${UBI_ARCH}.tar.gz"
RUN wget -O - "${RELEASE_URL}" \
    | tar --directory /usr/local/bin --extract --gzip --no-same-owner ubi


FROM scratch
# UBI needs at least `/tmp` to exist when running:
COPY --from=scratch / /tmp
COPY --from=downloader /usr/local/bin/ubi /ubi
ENTRYPOINT ["ubi"]
CMD ["--help"]

# Build it:
docker build --build-arg RELEASE_VERSION=v0.9.0 --tag localhost/ubi:0.9.0 .

# Run it:
docker run --rm -it localhost/ubi:0.9.0

[autarch]

Yes, I agree that this would be useful. A PR for this would be great!

[autarch]

Looking at how this was done for just, I see that the Dockerfile downloads a GitHub release using wget. For ubi, I'd prefer that the Dockerfile use the ubi bootstrap script (see the project docs), for the sake of dogfooding.

Also, I saw the discussion in the just PR about what base image to use. I'm happy with a minimal alpine image so that folks can just run it directly, rather than having to create a new image that copies ubi in (that seems kind of annoying).

[polarathene]

TL;DR: Based on the verbose response below, I've made some tradeoffs to the Dockerfile that would fit your project needs better I think?

# syntax=docker/dockerfile:1

FROM alpine
# Provide an UBI release tag for `bootstrap-ubi.sh` to use
# (otherwise defaults to latest tag at GH Releases):
ARG TAG
RUN --mount=type=bind,source=./bootstrap/bootstrap-ubi.sh,target=/boostrap-ubi.sh \
  sh /bootstrap-ubi.sh
ENTRYPOINT ["ubi"]
CMD ["--help"]

How do you feel about that simplified Dockerfile instead?

Summary of changes:

• Doesn't bother optimizing the image for size (FROM scratch + COPY of only ubi), simplifying the image by keeping Alpine.
• RUN --mount is used (adds minor complexity) to avoid a COPY:
  • I haven't checked if the bootstrap script was committed with +x, so I'ved invoked it via sh.
  • Usage of the script makes SHELL a tad redundant, so I've dropped that as well.
  • Ownership of the extracted ubi executable hasn't been corrected when the user is root (issue of your bootstrap script), a && chown 0:0 /usr/local/bin/ubi could be added here or better your bootstrap script could be updated with that fix (alternatively use the --no-same-owner option via tar).
• RELEASE_TAG => TAG to align with your request to use the bootstrap script instead.
• Dropped an optimization to better support building images for foreign archs (via an asset fetch stage that avoided triggering QEMU emulation):
  • Your bootstrap script doesn't support that approach well (needs ability to customize the desired arch instead of uname -m detection).
  • The optimization also added complexity that some maintainers rather avoid (especially if they aren't that comfortable with more advanced Dockerfile).
  • As the image is quite simple to build and most likely only an optimization relevant for your CI, favoring a simpler Dockerfile to grok as a maintainer seems more important. If you had a stage that built from source or installed packages, it can be more beneficial.

Optional: The RUN --mount could be dropped too if you prefer, it's only relevant to avoid the weight of the bootstrap script which is only temporarily needed (a remote fetch via curl/wget should be avoided IMO however):

# syntax=docker/dockerfile:1

FROM alpine
ARG TAG
COPY ./bootstrap/bootstrap-ubi.sh /boostrap-ubi.sh
RUN /bootstrap-ubi.sh
ENTRYPOINT ["ubi"]
CMD ["--help"]

---

Reference

This section is mostly for reference, no expectation for you to read through it all 👍

Common Dockerfile patterns for projects

Looking at how this was done for just, I see that the Dockerfile downloads a GitHub release using wget.

Yeah, there's a few approaches I've seen commonly used:

• Separate builder stage that uses COPY with a local git clone and builds the project from source.
  • ➕ Useful for custom builds without requiring any setup experience from the user.
  • ➖ Notably heavier to perform on disk (and resources like CPU/RAM) and can take significantly longer.
  • I generally prefer this kind, or at least the option for a containerized build (especially for projects where I may want to do my own variation of an image a bit differently than what upstream would accept/approve).
• No containerized build stage, but COPY the build artifact from an external source instead.

  • ❌ CoreDNS does this, but I'm not a fan as it's inconvenient if you're not familiar with the project (if it's not straight-forward like with Prometheus IIRC) or you don't have the expected dev environment setup and familiarity to build such projects.

    • Mostly useful for convenience of project authors and their CI.

    • For UBI, you could either fetch the binaries prior to the Dockerfile build, or as a post-step to your own release workflow if a single runner produces all artifacts, the Dockerfile becomes rather simple (adapted from this example):

      FROM alpine
      ARG TARGETARCH TARGETVARIANT
      COPY ./releases/${TARGETARCH}${TARGETVARIANT}/ubi /usr/local/bin/ubi
      ENTRYPOINT ["ubi"]

      In some cases it could be only two lines (but not useful as a runtime image).

  • ✔️ Can technically work as a simple way to package a build artifact for distribution via an image.

    • It however would have very little utility than what is generally expected of a Dockerfile (to anyone that would want to use that themselves beyond your own CI).
    • It was argued for just (by me to those requesting just publishes container images) that just was simple enough to acquire (a bit more than ubi due to distro packages availability) that upstreaming a workflow to publish an image was questionable.
      • I had since helped quite a bit with review support for the PR author attempting to upstream such to just anyway (repeatedly disproving their assumptions to justify it).
      • When contributed properly it can alleviate a fair amount of burden from maintainers at least. An image for UBI would be quite convenient given it's functionality (although there's still the concern with checksum verification + associated UBI issue).
• No containerized build stage, or COPY but just remotely fetch a published release.
  • ➕ Build process skipped for convenience. Quite useful when builds already exist and you just want a specific release.
  • ➕ Like the COPY option (with external build) the Dockerfile is still relatively simple.
  • ➕ Convenient in CI on Github with the on.release event trigger with the relevant context.
    • Typically simpler than integrating with an existing build workflow (see some caveats I've documented regarding complexity), especially when it can come to publishing multi-arch images if multiple build runners were invoked (eg amd64 + arm64) for native build perf.
    • If it were triggered by another event like on.push and filtered by tags, you'd need to delay until the GH release artifacts were available, so instead similar to if adapted for the COPY approach (with an external build) utilizing workflow_call could keep the workflow cleanly separated but then depends on the caller's permissions. on.release + workflow_dispatch is far easier to reason with for maintenance.
  • ➖ Without local COPY it's not really suitable for projects that would publish regular images reflecting the state of a development branch. Mostly mitigated if your project can compromise with pre-release tags, or the project is small/simple enough not to need such pre-release channels in the first place.
  • ➖ May be more complicated if needing to map the platform/arch, something that an external build with COPY effectively makes implicit.

FROM scratch vs FROM alpine for the runtime image published

Beyond that is the decision to just ship a FROM scratch with only the binary, or if it'd be more convenient to add to FROM alpine.

• UBI only needs /tmp to be present AFAIK, unlike other tools like just which expects a shell to invoke.
• It can still be convenient to have a container you can shell into to experiment with (and for just avoids some UX concerns](Add container image support with multi-arch builds casey/just#2851 (comment))). While a user could just build a local image to test, or in some cases use nsenter when a shell isn't present, Alpine doesn't add much extra weight.
• The Deno project approaches this with several variants for the base image (with a bin tag that just provides the binary in a FROM scratch image). If glibc vs musl was relevant for UBI you could go with Alpine and a glibc base, but I don't think this matters much, Alpine alone would be sufficient for providing convenience.
• As another reference Astral's UV image has a latest tag (and semver tags) associated to their FROM scratch base, with separate debian + alpine tags for the base image variants.`

Current tagging: houseabsolute/ubi:0.9.0 + houseabsolute/ubi:0.9 + houseabsolute/ubi:latest

That would remain the same for the bin, and if needed an -alpine variant suffix could be used.

It would however add a bit more complexity to the workflow to support an image variant, so for now unless someone requests it, I'd say it is probably better to keep this simple and decide on an image with either only the UBI binary or UBI binary + Alpine base.

• Alpine:
  • Easy ephemeral environment to quickly try UBI out, maybe download/install a release of something and try that out within the same container.
• Scratch:
  • Less image weight, no wasted bandwidth pulling an Alpine image layer (4MB compressed).
  • Not too useful directly interactively beyond testing, would really only serve convenience in other Dockerfile to run UBI more easily for building images.
  • Could potentially be useful by tools that can fetch an OCI artifact (maybe oras or proto come to mind).

Largely depends on if you'd like the container to be more useful on it's own, and if your users (or future potential users) would appreciate that.

• I'm the only one who's expressed interest in an image thus far, so perhaps take the approach of UV and just publish with FROM scratch, and add an image variant in future if there's demand for it.
• If the scratch image keeps the binary at /usr/local/bin, you could also add Alpine later (without a variant) without it really being a breaking change.
• For the bootstrap request you made, it's instead simpler for you to just keep the Alpine base and use that as-is (like shown in the next section). I'm fine with that too 👍

---

Adapting to bootstrap script

For ubi, I'd prefer that the Dockerfile use the ubi bootstrap script (see the project docs), for the sake of dogfooding.

Remote install scripts are generally discouraged for container builds for security/transparency reasons. Like you highlight in your own README:

ubi/README.md

Lines 354 to 359 in e061108

	### Is this Better Than Installing via `curl https://some.site/random/installer.sh | sh`?
	Isn't literally anything else better than this?
	In all seriousness, `ubi` does not download arbitrary code from a random website and execute it
	locally when you install anything. That seems like a good thing.

That said since it is a part of this repo, we could COPY or RUN --mount=type=bind the bootstrap-ubi.sh file.

If ignoring the suggested build optimization (described below in next section), it would look like this (if we don't just keep the alpine base image instead of publishing only a scratch image with the ubi binary):

# syntax=docker/dockerfile:1

FROM alpine
ARG TAG
RUN --mount=type=bind,source=./bootstrap/bootstrap-ubi.sh,target=/boostrap-ubi.sh \
  sh /bootstrap-ubi.sh
ENTRYPOINT ["ubi"]
CMD ["--help"]

Not much need for SHELL if all we're doing is invoking a shell script (the --mount instead of COPY will ensure the bootstrap script isn't included in the image).

Slight compatibility concerns with current bootstrap script

Your script just doesn't correct for the scenario of running as root:

ubi/bootstrap/bootstrap-ubi.sh

Line 233 in e061108

tar -xzf "$LOCAL_FILE" ubi

For non-root users the ownership from the archive will be corrected to their user/group, but when tar extracts as root the archived ownership is preserved unless using --no-same-owner.

• Technically I don't think the ownership mismatch causes a problem for /usr/local/bin executables, the chmod +x applies the executable bit to all octals (ugo) unlike other modifications like +r/+w IIRC.
• You could alternatively correct this in your CI prior to putting the build into a tar archive, but it's a common mistake I see across projects publishing to GH Releases.

That said, your bootstrap script is more thorough if you wanted to publish images beyond the common amd64 + arm64 variants I've proposed.

• Since you already cover the Go arch conventions, the mapping workaround I have with UBI_ARCH in the Dockerfile could also be dropped in favor of setting UBI_ARCH=${TARGETARCH}${TARGETVARIANT}
• However, your script infers the arch via uname -m, I'm using ${BUILDPLATFORM} in the Dockerfile to enforce the downloader to run with an arch that is native to the host system. This avoids needing QEMU and slower arch emulation for foreign targets.
  • It is an optimization that is mostly only relevant to CI and for a basic operation of this shell script + curl / tar, it might not be that important. I assume most users would just build on a system for the arch they'd want, if not directly using the published images you'd supply.
  • If you did want to retain the optimization, your script would need to [support an ARCH environment variable] or similar (like UBI_ARCH / BIN_ARCH / RELEASE_ARCH).

Rough example of what the Dockerfile might look like with ARCH ENV supported by the bootstrap:

# syntax=docker/dockerfile:1

# `BUILDPLATFORM` + `TARGETARCH` + `TARGETVARIANT` are implicitly defined by BuildKit:
# https://docs.docker.com/reference/dockerfile/#automatic-platform-args-in-the-global-scope
FROM --platform=${BUILDPLATFORM} alpine AS downloader
SHELL ["/bin/ash", "-eux", "-o", "pipefail", "-c"]
ARG TAG TARGETARCH TARGETVARIANT
ARG ARCH="${TARGETARCH}${TARGETVARIANT}"
COPY ./bootstrap/bootstrap-ubi.sh /boostrap-ubi.sh
RUN sh /bootstrap-ubi.sh

FROM alpine
COPY --from=downloader /usr/local/bin/ubi /usr/local/bin/ubi
ENTRYPOINT ["ubi"]
CMD ["--help"]

I think it may be simpler with the earlier Dockerfile shown for your bootstrap script, ignoring the optimization and keeping it simple by keeping Alpine in the final image.