alpine-toolbox

Description

Alpine Toolbox is a minimal Docker image based on Alpine Linux, designed to provide a lightweight and efficient environment for various command-line tasks. It includes essential tools and utilities commonly used in development, scripting, and system administration as well as debugging and testing.

TL;DR

• Use :latest for the non-root OpenShift-friendly image and :root if you explicitly need runtime apk add.
• Images are published for linux/amd64 and linux/arm64.
• Alpine package pins are updated by the scheduled Alpine updater workflow, while Renovate handles GitHub-sourced binaries such as yq and catatonit.
• The image is designed around UID 10001 and GID 0 so it works well on vanilla Kubernetes and OpenShift.

Images & tags

We publish two variants so you can choose what fits your platform:

• Non-root (OpenShift-friendly) Tags: ghcr.io/containeroo/alpine-toolbox:latest, ghcr.io/containeroo/alpine-toolbox:<version>

  • Runs as UID 10001, GID 0 by default.
  • Compatible with vanilla Kubernetes and OpenShift restricted policies.
  • Best for production and clusters that require non-root.
  • Runtime apk add is not supported (install at build time or use user-space binaries).

• Root (runtime installs) Tags: ghcr.io/containeroo/alpine-toolbox:root, ghcr.io/containeroo/alpine-toolbox:<version>-root

  • Runs as root by default.
  • Allows apk add at runtime.
  • On OpenShift you’ll need an SCC that allows root (e.g., anyuid).

Quick start

# Non-root (recommended)
docker run --rm -it ghcr.io/containeroo/alpine-toolbox:latest sh

# Root (allows runtime apk)
docker run --rm -it ghcr.io/containeroo/alpine-toolbox:root sh

Packages

alpine linux (3.23.4 AS builder 3.23.4) with following components:

• bash (5.3.3-r1)
• bind-tools (9.20.26-r0)
• catatonit (0.2.1)
• coreutils (9.8-r1)
• curl (8.20.0-r0)
• gettext (0.24.1-r1)
• git (2.52.0-r0)
• inetutils-telnet (2.6-r0)
• jq (1.8.1-r0)
• openssl (3.5.7-r0)
• rsync (3.4.3-r0)
• tzdata (2026c-r0)
• xmlstarlet (1.6.1-r2)
• yq (4.53.2)

The list and versions are auto-updated by CI from the Dockerfile.

Dependency updates

• Alpine packages are updated by the scheduled GitHub workflow in .github/workflows/update-alpine-packages.yaml, which reads the official Alpine APKINDEX metadata for the Alpine version pinned in the Dockerfile.
• Renovate remains enabled for non-Alpine dependencies such as GitHub release and tag based binaries.

Package missing?

Feel free to create an issue or a pull request to add any missing package you need. Please keep the image small and follow naming conventions.

User & Group Model (Why UID 10001 and Group 0)

This image is built to run safely as non-root on vanilla Kubernetes and OpenShift, while still allowing write access where needed.

TL;DR: use a stable non-root UID, make writable paths group-owned by 0, and set g+w. That keeps the image portable across Kubernetes and OpenShift arbitrary-UID execution.

Why UID 10001?

• Non-root by default. Using a fixed, high, non-system UID like 10001 makes the image safe in vanilla Kubernetes and most CI/CD runners without extra flags.
• Low collision risk. High UIDs are unlikely to clash with host/system accounts inside the container.
• Portable. In OpenShift, the platform may override the UID at runtime with an arbitrary, non-root UID. Starting from a non-root UID keeps behavior consistent across platforms.

Why Group 0 (root group)?

• Arbitrary-UID compatibility (OpenShift). OpenShift commonly runs containers with a random non-root UID, and includes group 0 in the process’s groups.
• Make dirs group-writable. If your writable paths are group-owned by 0 and have group-write permissions, the arbitrary UID can still write there because it’s in group 0.
• No special privileges. Being in group 0 ≠ root. Privileges come from UID 0 or Linux capabilities, not from the group number. We also drop capabilities in the pod security context.