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
- The support matrix — where Alpine sits among the other families
01 One small system
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.inihas[META]withGroup=alpine,Variant=cloud, and two sections,alpine-cloud-3.x86_64andalpine-cloud-3.aarch64, bothBoot=efiandRelease=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 butalpinegets 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).
Read more
02 The image and its bare hash
…/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.qcow2andSHA512SUMS=the same URL plus.sha512; for aarch64alpine-3.24.4-aarch64-cloudinit-r0.qcow2(alpine.ini:8-20).SHA512SUMS=gives thedownload-with-sha512sumsrule (rulegen.py:498-502). Its reader takesHASH 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
cloudinitimages carry cloud-init, where Alpine's other cloud images use its own tiny-cloud, is Alpine's practice (derived).
Read more
03 What the first boot does on Alpine
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/rootandalpine/alpinein groupusers, withsudo: ["ALL=(ALL) NOPASSWD:ALL"]andshell: /bin/bash(010-qemu.mk:200-211, rulegen.py:467); the host name isalpine-3(010-qemu.mk:94-104). - With a pkgproxy: no
bootcmdsetup script (aptonly fordebianandubuntu) and noruncmdone (snapfor every group butalpine) (010-qemu.mk:129-130); both batches still addpkgproxyto/etc/hosts(010-qemu.mk:132-134, 010-qemu.mk:156-168), andGOPROXYis 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/aptexists (010-qemu.mk:244). No file undermk/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
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/gruband- grub-mkconfig -o /boot/grub/grub.cfg, thenpackages:withbash,sudoandtar(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
runcmdlist, which ends the common template (010-qemu.mk:238-246): they run aftertouch /etc/cloud/cloud-init.disabled, in the same first boot. ALPINE_CLOUD_INIT_USER_DATA_TEMPLATEis 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 ofalpine-cloud-3that have no template of their own.- The common template gives both users
shell: /bin/bashand 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-3withusername: alpine,password: alpine(spread-demo/spread.yaml:188-191).
05 Worth knowing before you test on Alpine
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-3with 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).
Read more
06 Where to go from here
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
- How a user-data template is chosen, changing what cloud-init does, running spread.
- What pkgproxy adds to user-data, checksum keys, the support matrix.
- The other distribution decks: Debian, openSUSE, Gentoo, and the 64-bit Arm machine.
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
| System | Release | Point release in the URL | Boot | Image | Host name |
|---|---|---|---|---|---|
alpine-cloud-3.x86_64 | 3 | 3.24.4 | efi | alpine-3.24.4-x86_64-cloudinit-r0.qcow2 | alpine-3 |
alpine-cloud-3.aarch64 | 3 | 3.24.4 | efi | alpine-3.24.4-aarch64-cloudinit-r0.qcow2 | alpine-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
| What | On Alpine | Source |
|---|---|---|
| Users | root/root; alpine/alpine in group users, sudo rule, shell /bin/bash | 010-qemu.mk:200-211 |
| Host name | alpine-3 | 010-qemu.mk:94-104 |
| SSH | password logins, root may log in | 010-qemu.mk:212-243 |
| apt sources | nothing: there is no /etc/apt | 010-qemu.mk:244 |
| pkgproxy, bootcmd | /etc/hosts entry and reachability probe (curl, or wget as BusyBox has it); no setup script | 010-qemu.mk:127-162 |
| pkgproxy, runcmd | /etc/hosts entry again; no snap setup, for Alpine alone | 010-qemu.mk:164-168 |
| pkgproxy, files | GOPROXY appended to /etc/environment | 010-qemu.mk:170-180 |
| Distribution quirks | none 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
- The support matrix — every family and architecture side by side
SPREAD · tests
- Running spread on image-garden — running spread on the systems image-garden makes
FIRST BOOT · cloud-init changes
- How a user-data template is chosen — how a template for the alpine group is picked
- Changing what cloud-init does — where a project's template and hooks live
PKGPROXY · caching for guests
- What pkgproxy adds to user-data — what pkgproxy adds to the first boot, and what Alpine skips
BUILD TIME · data and rules
- Every image has a checksum — for contributors, how each image names its checksum, Alpine's bare hash among them