Alpine Linux

one release, small for users

image-garden has one Alpine system, alpine-cloud-3, on x86_64 and aarch64 with EFI, pinned to one point release and checked against the bare SHA-512 hash Alpine publishes beside the image; the first boot gives an alpine user, and with pkgproxy only /etc/hosts and GOPROXY, no snap setup.

On the map: systems

▶ Watch this deck — 6 scenes, ~5 min

Worth seeing first

01 One small system

ALPINE LINUX the smallest Linux, without the GNU userland alpine-cloud-3.x86_64 alpine-cloud-3.aarch64 efi efi the image it downloads: …/v3.24/…/alpine-3.24.4-x86_64-… the name's 3: the major version the point release is pinned, and moves with image-garden every other family: pkgproxy's snap setup Alpine: no snap setup the download the first boot a spread template what to watch for
Alpine Linux, the smallest system and one without the GNU userland: alpine-cloud-3.x86_64 and alpine-cloud-3.aarch64, both booting with EFI. The 3 is the major version; the point release, 3.24.4, is pinned in image-garden, which moves it forward. Every other family gets pkgproxy's snap setup, Alpine none. The deck covers the download, the first boot, a spread template and what to watch for

Two systems, alpine-cloud-3.x86_64 and alpine-cloud-3.aarch64, both booting with EFI, each pinned to one point release that a new image-garden moves forward.

Sometimes you want the smallest Linux you can get, or you want to know whether your tool works without the GNU userland everyone else ships. That's Alpine. image-garden has one Alpine system, alpine-cloud-3, for x86_64 and aarch64, and both boot with EFI firmware. The three is Alpine's major version; the exact point release is pinned in image-garden, which moves it forward as Alpine publishes new ones. Next to ubuntu-cloud-24.04.x86_64, Alpine is the odd one out: it's the only family that gets no snap setup from pkgproxy. This deck shows where its image comes from, what the first boot does, a template that makes it ready for spread, and what to watch for.

Details and sources

Details

  • data/alpine.ini has [META] with Group=alpine, Variant=cloud, and two sections, alpine-cloud-3.x86_64 and alpine-cloud-3.aarch64, both Boot=efi and Release=3 (alpine.ini:4-20).
  • The URLs pin Alpine 3.24.4 (alpine.ini:9, alpine.ini:16); the README says "3 (currently 3.24.4)" (README.md:615-619), and NEWS records each move of the point release, the latest "updated to release 3.24.4, from 3.24.1" (NEWS:88).
  • PKGPROXY_RUNCMD_SETUP = $(if $(filter alpine,$1),,snap): every group but alpine gets pkgproxy's snap script (010-qemu.mk:130).
  • That Alpine is built on musl and BusyBox rather than glibc and GNU tools is general knowledge (derived).

02 The image and its bare hash

A BARE HASH Alpine's download network: one directory per minor release https://dl-cdn.alpinelinux.org/alpine/v3.24/releases/cloud/ alpine-3.24.4-x86_64-cloudinit-r0.qcow2 cloudinit the flavour with cloud-init, which reads the seed …/alpine-3.24.4-x86_64-cloudinit-r0.qcow2.sha512 Debian's SHA512SUMS: a line per file HASH debian-13-…-daily.qcow2 Alpine's .sha512: one line HASH accepted: the file's only line, 128 hex digits for SHA-512 a newer point release a new URL a new cached file a fresh download
alpine-cloud-3.x86_64 downloads alpine-3.24.4-x86_64-cloudinit-r0.qcow2 from dl-cdn.alpinelinux.org, the cloudinit flavour, with cloud-init to read the seed. Beside it, the .sha512 file holds one bare hash, where Debian's SHA512SUMS has a hash and a name per line; image-garden accepts a lone line of the right length. A newer point release in a new image-garden means a new URL, a new cached file and a fresh download

…/alpine/v3.24/releases/cloud/alpine-3.24.4-x86_64-cloudinit-r0.qcow2, checked with SHA-512 against the bare hash in ….qcow2.sha512.

Alpine publishes its cloud images on its download network, in a directory for each minor release. image-garden takes the cloudinit flavour, the one with cloud-init inside, because that's what reads the seed. Beside each image sits a file with the same name plus .sha512. Unlike Debian's list, it holds one thing: a bare hash, with no file name after it. image-garden's checksum reader accepts that when it's the file's only line and has the right length, so the image is checked against that file with SHA-512. And because the system is just alpine-cloud-3, a newer point release in a new image-garden means a new URL, a new file in your cache, and a fresh download.

Details and sources

Details

  • URL=https://dl-cdn.alpinelinux.org/alpine/v3.24/releases/cloud/alpine-3.24.4-x86_64-cloudinit-r0.qcow2 and SHA512SUMS= the same URL plus .sha512; for aarch64 alpine-3.24.4-aarch64-cloudinit-r0.qcow2 (alpine.ini:8-20).
  • SHA512SUMS= gives the download-with-sha512sums rule (rulegen.py:498-502). Its reader takes HASH NAME, HASH *NAME, the BSD format, or a file whose only non-empty line is a bare hash of the right length, "as published by Alpine Linux next to each image" (image-garden:75-92, data/README.md:59-61). NEWS: Alpine images were checked against a hash copied into image-garden by hand until this format was accepted (NEWS:166-170).
  • The local file name is the URL's last part, so each point release is its own file in $(GARDEN_DL_DIR)/alpine/; the system's link moves to the new one when the URL changes (see when upstream moves on). The old file stays until you delete it.
  • That the cloudinit images carry cloud-init, where Alpine's other cloud images use its own tiny-cloud, is Alpine's practice (derived).

03 What the first boot does on Alpine

FIRST BOOT root / root alpine / alpine alpine-3 host name with a pkgproxy in reach: the least of any family /etc/hosts: the name pkgproxy GOPROXY in /etc/environment apt setup snap setup skipped for Alpine alone probe pkgproxy curl, when there is one else wget, BusyBox's too Alpine's packages: straight from its mirrors, uncached
Alpine gets root with password root and alpine with password alpine, host name alpine-3. With a pkgproxy in reach it gets only the pkgproxy entry in /etc/hosts and GOPROXY: no apt setup and, for Alpine alone, no snap setup. The probe uses curl, or wget with options BusyBox's wget understands. Alpine's packages come uncached from its mirrors

Users root/root and alpine/alpine, host name alpine-3. With pkgproxy: /etc/hosts and GOPROXY only; no apt, no snap.

Alpine's first boot uses the same common user-data as everyone else. You get root, password root, and a user called alpine, password alpine, and the host name alpine-3. With pkgproxy in reach, Alpine gets the least of any family. pkgproxy's name goes into /etc/hosts, and the go command gets GOPROXY. That's all. There's no apt to set up, and image-garden skips the snap script for Alpine alone. The probe that checks whether pkgproxy answers uses curl when there is one, or falls back to wget, with options BusyBox's wget understands too. Packages from Alpine's own package manager come straight from its mirrors, uncached.

Details and sources

Details

  • Users: root/root and alpine/alpine in group users, with sudo: ["ALL=(ALL) NOPASSWD:ALL"] and shell: /bin/bash (010-qemu.mk:200-211, rulegen.py:467); the host name is alpine-3 (010-qemu.mk:94-104).
  • With a pkgproxy: no bootcmd setup script (apt only for debian and ubuntu) and no runcmd one (snap for every group but alpine) (010-qemu.mk:129-130); both batches still add pkgproxy to /etc/hosts (010-qemu.mk:132-134, 010-qemu.mk:156-168), and GOPROXY is appended to /etc/environment (010-qemu.mk:170-180).
  • The probe uses curl, else wget with -q -T 5 -t 1; the comment says "GNU wget would try 20 times; busybox wget takes -t and ignores it", and a guest with neither leaves no mark (010-qemu.mk:141-148).
  • The apt rewrite runs only where /etc/apt exists (010-qemu.mk:244). No file under mk/ names Alpine.
  • That Alpine has no snapd and installs packages with apk is general knowledge (derived); the code gives no reason for leaving Alpine out of the snap script.

04 A template that gets Alpine ready for spread

A TEMPLATE FOR SPREAD spread-demo/.image-garden.mk define ALPINE_CLOUD_INIT_USER_DATA_TEMPLATE endef $(CLOUD_INIT_USER_DATA_TEMPLATE) the common template packages: - bash - sudo - tar for spread shell: /bin/bash sudo: ["ALL=(ALL) NOPASSWD:ALL"] already in the common one - sed … 's/GRUB_TIMEOUT=[0-9]+/GRUB_TIMEOUT=0/' … - grub-mkconfig -o /boot/grub/grub.cfg no menu wait for the alpine group: alpine-cloud-3.x86_64 and alpine-cloud-3.aarch64
spread-demo/.image-garden.mk defines ALPINE_CLOUD_INIT_USER_DATA_TEMPLATE: the common template, two runcmd lines that set GRUB_TIMEOUT=0 and run grub-mkconfig, and packages bash, sudo and tar for spread. The common template gives the users shell /bin/bash and a sudo rule, so these packages make sure both exist. Named for the alpine group, it covers alpine-cloud-3 on x86_64 and aarch64

ALPINE_CLOUD_INIT_USER_DATA_TEMPLATE in spread-demo/.image-garden.mk: the common template, two GRUB lines and packages: bash, sudo, tar.

If you run spread on Alpine, look at image-garden's own spread demo. Its .image-garden.mk carries a short Alpine template. It starts from the common template, so everything you've just seen stays. Then it adds a packages list: bash, sudo and tar, for compatibility with spread, as its comment says. The common template already gives both users bash as their shell, and the second user a sudo rule, so these packages make sure both are there. Two more runcmd lines set GRUB's timeout to zero and rebuild its configuration, so every boot skips the menu wait. Named for the alpine group, it covers alpine-cloud-3 on both architectures. Copy it into your project.

Details and sources

Details

  • The template, with its comment "For compatibility with spread, pre-install sudo and bash, xz and GNU tar. Edit grub configuration for the system to boot faster.": $(CLOUD_INIT_USER_DATA_TEMPLATE), then - sed -i -E -e 's/GRUB_TIMEOUT=[0-9]+/GRUB_TIMEOUT=0/' /etc/default/grub and - grub-mkconfig -o /boot/grub/grub.cfg, then packages: with bash, sudo and tar (spread-demo/.image-garden.mk:4-14). The comment names xz, which the list does not install.
  • The two lines join the common template's runcmd list, which ends the common template (010-qemu.mk:238-246): they run after touch /etc/cloud/cloud-init.disabled, in the same first boot.
  • ALPINE_CLOUD_INIT_USER_DATA_TEMPLATE is the group name the picker tries after the release and instance names (010-qemu.mk:293-298), so it applies to both architectures, and to named instances of alpine-cloud-3 that have no template of their own.
  • The common template gives both users shell: /bin/bash and the second user a sudo rule (010-qemu.mk:200-211). Whether Alpine's cloud image ships bash, sudo and GNU tar is not in the source (derived: a minimal Alpine has BusyBox's ash and tar).
  • The spread demo's system entry: alpine-cloud-3 with username: alpine, password: alpine (spread-demo/spread.yaml:188-191).

05 Worth knowing before you test on Alpine

WORTH KNOWING musl, not glibc a binary built on Ubuntu or Fedora may not even start build in the guest, or link statically BusyBox fewer options than the GNU tools: a script can fail on one flag apk and OpenRC no apt, and no systemd: there is no systemctl no snapd and no snap setup from pkgproxy small and quick to boot: a cheap extra system in a test matrix
On Alpine: musl, not glibc, so binaries built elsewhere may not start, build in the guest or link statically; BusyBox tools take fewer options than GNU ones; apk packages and OpenRC services, no systemctl; no snapd. The image is small and boots fast, a cheap extra system in a test matrix

musl, not glibc; BusyBox tools; apk; OpenRC, not systemd; no snapd. Small and quick to boot.

Some things on Alpine catch people out. Its C library is musl, not glibc, so a binary built on Ubuntu or Fedora may not even start there; build it inside the guest, or link it statically. Its everyday tools come from BusyBox, which takes fewer options than the GNU versions, so a script that works elsewhere can fail on a single flag. Packages come from apk, and services run under OpenRC, not systemd, so there's no systemctl. There's no snapd either. On the bright side, the image is small and boots fast, which makes Alpine a cheap extra system in a test matrix: a quick check that your tool doesn't quietly depend on any of that.

Details and sources

Details

  • Everything on this slide is general knowledge about Alpine Linux (derived): musl libc, BusyBox, apk, OpenRC, no snapd. The source shows its marks: no snap setup for the group alpine (010-qemu.mk:130), a probe written for BusyBox's wget (010-qemu.mk:141-148), and the spread demo installing bash, sudo and GNU tar (spread-demo/.image-garden.mk:4-14).
  • image-garden's CI tests alpine-cloud-3 with spread on both architectures; on a Raspberry Pi 5 the aarch64 job took 2.6 minutes, the shortest of its jobs (.gitlab-ci.yml:889-895).

06 Where to go from here

ROADS Alpine Linux Template lookup how ALPINE_… is picked Cloud-init hooks where templates live Spread tests on these systems pkgproxy in user-data what Alpine skips Every image has a checksum for contributors The support matrix every family side by side
Roads from Alpine Linux: how a template is chosen, changing what cloud-init does, running spread, pkgproxy in the user-data, checksums for contributors and the support matrix

Next: templates, cloud-init hooks, spread, pkgproxy in the user-data, checksums and the support matrix.

So Alpine is one system on two architectures, a bare hash beside its image, a first boot with the least pkgproxy setup of any family, and a short template that gets it ready for spread. From here, the template deck shows how a template for the alpine group is picked, and the hooks deck where a project keeps its templates. The spread deck shows how tests run on these systems. The pkgproxy deck goes through what the proxy adds and what Alpine skips, the checksums deck, for contributors, how each image names its checksum, and the support matrix sets Alpine beside every other family.

Details and sources

Read more

Basis of the statements on this page

Read in data/alpine.ini, rulegen.py, mk/010-qemu.mk, the image-garden script, data/README.md, spread-demo/.image-garden.mk, README.md, NEWS and .gitlab-ci.yml of image-garden at the commit in garden.commit ("code"). What Alpine is built from, musl, BusyBox, apk and OpenRC, is general knowledge ("derived"). Nothing was run for this page.

The Alpine systems

SystemReleasePoint release in the URLBootImageHost name
alpine-cloud-3.x86_6433.24.4efialpine-3.24.4-x86_64-cloudinit-r0.qcow2alpine-3
alpine-cloud-3.aarch6433.24.4efialpine-3.24.4-aarch64-cloudinit-r0.qcow2alpine-3

Image URL and checksum file

image     https://dl-cdn.alpinelinux.org/alpine/vMAJOR.MINOR/releases/cloud/alpine-VERSION-ARCH-cloudinit-r0.qcow2
checksum  the image URL + .sha512

ARCH is x86_64 or aarch64. The .sha512 file holds one bare SHA-512 hash, which the download helper accepts as the file's only non-empty line of 128 hex digits; it is saved in the cache as FILE.sha512sums. A new point release in a new image-garden is a new file name, so it is downloaded afresh; the old one stays in the cache's alpine/ directory until you remove it.

What the first boot does

WhatOn AlpineSource
Usersroot/root; alpine/alpine in group users, sudo rule, shell /bin/bash010-qemu.mk:200-211
Host namealpine-3010-qemu.mk:94-104
SSHpassword logins, root may log in010-qemu.mk:212-243
apt sourcesnothing: there is no /etc/apt010-qemu.mk:244
pkgproxy, bootcmd/etc/hosts entry and reachability probe (curl, or wget as BusyBox has it); no setup script010-qemu.mk:127-162
pkgproxy, runcmd/etc/hosts entry again; no snap setup, for Alpine alone010-qemu.mk:164-168
pkgproxy, filesGOPROXY appended to /etc/environment010-qemu.mk:170-180
Distribution quirksnone in mk/per-distro quirks

The spread demo's Alpine template

From spread-demo/.image-garden.mk:4-14. Put it in your project's .image-garden.mk to get the same image:

# For compatibility with spread, pre-install sudo and bash, xz and GNU tar.
# Edit grub configuration for the system to boot faster.
define ALPINE_CLOUD_INIT_USER_DATA_TEMPLATE
$(CLOUD_INIT_USER_DATA_TEMPLATE)
- sed -i -E -e 's/GRUB_TIMEOUT=[0-9]+/GRUB_TIMEOUT=0/' /etc/default/grub
- grub-mkconfig -o /boot/grub/grub.cfg
packages:
- bash
- sudo
- tar
endef

Running the Alpine system

$ image-garden make alpine-cloud-3.x86_64.run
$ ./alpine-cloud-3.x86_64.run --query

In spread.yaml the system is alpine-cloud-3, with username: alpine and password: alpine (spread-demo/spread.yaml:188-191).

Roads from here

SYSTEMS · distributions

SPREAD · tests

FIRST BOOT · cloud-init changes

PKGPROXY · caching for guests

BUILD TIME · data and rules