os-alpine

Overview

Use for Alpine Linux systems, container images, and Alpine-related musl compatibility issues. Read the Linux foundation for target identification and shared diagnostic contracts. Musl is a C library, not a distribution; a musl binary does not prove the target is Alpine.

Mental model

Alpine combines musl libc, BusyBox utilities, apk packages, and normally OpenRC on booted hosts. A small image trades GNU/glibc assumptions for different interfaces; making it behave like another distribution through compatibility patches is not automatically the simplest solution.

Release and current changes

• Verified 2026-09-05: Alpine 3.24 is the current stable branch; edge is rolling development. Check the release table again before selecting a base image or upgrade path.
• Support differs by repository: main is typically supported for two years, while community is supported until the next stable release. An otherwise supported branch can contain community packages that no longer receive that coverage.
• Alpine 3.23 introduced apk-tools v3. Check apk --version and local help before relying on newer commands, configuration, or parsed output; apk tool version and repository/package format version are different facts.
• Alpine 3.24 deprecates qemu-binfmt in favor of user-mode QEMU binfmt.d configuration and the binfmt service. For emulation failures, check installed registration and host ownership rather than starting the obsolete service.
• Its setuptools 82 package removes pkg_resources; a tool broken after upgrading may need a supported dependency/code update, not a system-wide Python downgrade.

ABI and tool compatibility

• Prefer musl-compatible artifacts or build against the actual target. A glibc-linked executable can report “not found” even when the file exists because its ELF interpreter is unavailable. Inspect architecture and ELF interpreter/dependencies with trusted inspection tools before diagnosing PATH.
• gcompat implements a subset of glibc-compatible APIs; it is not a replacement glibc installation or a guarantee that arbitrary vendor binaries work. If upstream supports only glibc, a supported glibc-based image may be the correct deployment choice. Don't invent loader symlinks or fetch unofficial libc packages to suppress an error.
• BusyBox sh is normally ash. Check applet help; don't assume Bash syntax or GNU options for sed, date, find, or ps. Add a declared tool dependency only when the operation requires it.
• Check Python wheel/native-addon availability for musl and the target architecture. A smaller base image can trigger source builds and additional build dependencies; judge the complete deliverable, not only compressed base size.

apk and repository state

• Inspect /etc/apk/repositories, /etc/apk/world, installed versions, and package policy. Keep repositories on the same stable branch; testing belongs to edge. Don't combine stable and edge as a generic missing-package fallback.
• World records requested package constraints, not just installed files. Resolve conflicts against those constraints; don't use force flags that discard requirements merely to make the solver succeed.
• apk update refreshes indexes; apk upgrade changes installed packages. Review branch-upgrade instructions separately: --available reconciles against available repository versions and can downgrade packages. It is not a harmless diagnostic flag.
• Keep package signing enabled. Investigate keys, clock, index freshness, mirrors, and branch consistency on verification failure. Do not routinely use --allow-untrusted or turn HTTPS verification off.
• For images, declare runtime packages explicitly and isolate build dependencies in a stage or a named virtual dependency group. Removing a build group must leave required shared libraries available. Treat an image's mutable tag and immutable digest differently; rebuild deliberately for security updates.
• Preserve modified configuration and review .apk-new files. A successful package transaction does not show that a daemon loaded the intended configuration.

Services and persistence

• On an OpenRC host, use rc-service name status, rc-status, and rc-update show to inspect state. Starting a service now differs from adding it to a runlevel; inspect /etc/init.d and /etc/conf.d for the actual service configuration.
• OpenRC defaults to cgroup v2 in Alpine 3.19+; user services are available in 3.22+. Check the actual manager and cgroup setup rather than translating systemd commands mechanically. Ordinary Alpine containers often have no OpenRC boot lifecycle.
• Distinguish disk-backed installations from diskless/data modes. For diskless setups, inspect lbu inclusion and persistence configuration; approved changes may need lbu commit and package-cache handling to survive reboot. This overlay is not automatically a backup of all application data.
• Before a host release upgrade, review bootloader and filesystem notes and establish recovery access. GRUB updates can require installation to the actual boot device/EFI target; do not copy a generic device path into a command.

Example

Read Alpine package identity without refreshing indexes or changing packages:

set -eu
cat /etc/alpine-release
apk --version
apk --print-arch
apk info -v musl busybox apk-tools
apk policy musl

Policy reflects available local metadata; it is not evidence that repositories were refreshed or the package is the latest security revision.

Checklist

• Branch, repository support, architecture, libc, and apk version are identified.
• Binary and shell assumptions fit musl/BusyBox; compatibility failures stay visible.
• Package constraints, trust, runtime dependencies, and configuration are preserved.
• Init and persistence match the deployment mode; verification limits are stated.

References

• Release support and 3.24 release announcement.
• apk behavior, package/repository model.
• glibc compatibility, BusyBox.
• OpenRC and diskless persistence.