os-alpine git:20260905.c6d4efeA

Immutable. This exact content is served forever at /api/v1/blob/50e17202a55655b9.

---
name: os-alpine
title: "Alpine Linux Operations"
description: "Operate Alpine hosts and images with musl ABI awareness, apk repository discipline, OpenRC services, and persistent configuration."
license: Apache-2.0
compatibility: "An Alpine Linux target with its installed apk/BusyBox tools; OpenRC applies to booted systems that use it."
domains: devops
rules:
  - content(alpine)
  - content(musl)
---

## Overview

Use for Alpine Linux systems, container images, and Alpine-related musl compatibility issues. Read the [Linux foundation](../os-linux/SKILL.md) 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:

```sh
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](https://alpinelinux.org/releases/) and [3.24 release announcement](https://lists.alpinelinux.org/~alpine/announce/%3C20260609230455.2543c365%40ncopa-desktop.lan%3E).
- [apk behavior](https://wiki.alpinelinux.org/wiki/Alpine_Package_Keeper), [package/repository model](https://docs.alpinelinux.org/user-handbook/0.1a/Working/apk.html).
- [glibc compatibility](https://wiki.alpinelinux.org/wiki/Running_glibc_programs), [BusyBox](https://wiki.alpinelinux.org/wiki/BusyBox).
- [OpenRC](https://wiki.alpinelinux.org/wiki/OpenRC) and [diskless persistence](https://wiki.alpinelinux.org/wiki/Alpine_local_backup).