Snap, container or native package
snap, container, packages for everyone
The same make rules ship as the snap, the OCI container, distribution packages and a source build; they differ in which QEMU runs, where downloads are cached, whether pkgproxy, spread and swtpm come along, and how close they stay to upstream releases.
On the map: start here
01 The same rules, three ways in
The snap, the container and distribution packages or a source build all carry the same image-garden.mk. They differ in QEMU, cache location, the extras that come along, and how current they are.
Before your first image-garden make, you need image-garden itself, and there are three ways to get it. The snap, from the Snap Store. The container, which you run with docker or podman. Or a package from your distribution, or a build from source. Whichever you pick, the make rules inside are the same, so ubuntu-cloud-24.04.x86_64 is built the same way by each. What differs is everything around them: which QEMU runs, where the downloads are kept, whether pkgproxy, spread and swtpm come along, and how close each stays to the newest release. This deck takes them one at a time.
Details and sources
Details
- The README compares the three installs in one table: availability, QEMU, architectures, EFI firmware, swtpm, spread, pkgproxy, virtiofsd and the cache (README.md:91-112). The full comparison is under this deck.
- Every install runs the same
image-gardenscript on the sameimage-garden.mk, built fromdata/*.iniandmk/*.mkby the top-level Makefile (Makefile:48-64); the script runsmake -fon that file (image-garden:982-993).
Read more
- From a system's name to a running VM: the path one system takes, the same in every install.
02 The snap
snap install image-garden adds QEMU for the host architecture and pkgproxy as components, and the configure hook adds spread; other QEMUs, spread-plus and swtpm come on demand. Downloads live in ~/snap/image-garden/common/cache.
The snap is one command: snap install image-garden. Its install hook adds two components straight away: QEMU for your own machine's architecture, and pkgproxy, the caching proxy, which runs as a service of the snap and which guests use by default. Right after it, the configure hook adds spread. QEMU for the other architectures, spread-plus and swtpm are components too, added when you ask for them. The snap's QEMU is built from source with one small patch, the same one the container carries. Downloads go to ~/snap/image-garden/common/cache, which survives refreshes. Strict confinement means a few paths move, so keep your projects under your home directory.
Details and sources
Details
- The install hook runs
snapctl install +qemu-<host arch> +pkgproxy, unless the snap was sideloaded (a revision such asx1) (snap/hooks/install:6-14). - The configure hook, which snapd runs at install too, installs
+spreadwhile thespread-variantsetting is empty (snap/hooks/configure:83-92); the README says so (README.md:163-169). - The components are
spread,spread-plus,qemu-x86-64,qemu-aarch64,qemu-riscv64,qemu-s390x,qemu-ppc64,qemu-loongarch64,pkgproxyandswtpm(snap/snapcraft.yaml:45-119). The README shows how to add one:snap install image-garden+qemu-aarch64(README.md:309-334). - The snap builds QEMU with
qemu-patches/guestfwd-unix-socket.patch(snap/snapcraft.yaml:341), the patch the container applies too (Dockerfile:29-32). - In the snap,
GARDEN_CACHE_DIRis$SNAP_USER_COMMON/cache, which is~/snap/image-garden/common/cache(mk/000-garden.mk:9-12). The common directory is not tied to a revision (derived from snapd's layout).
03 The container
One image with QEMU for six architectures, swtpm and OVMF. Run it with --device /dev/kvm and a volume at /var/cache/image-garden; name a pkgproxy with PKGPROXY_URL.
The container suits you when you'd rather install nothing on the host, or want every CI runner to carry exactly the same tools. It's one image, for 64-bit x86 and Arm hosts, with QEMU for all six guest architectures built in, patched like the snap's, plus swtpm and the Secure Boot firmware. You run it with docker or podman, and pass it two things: the KVM device, and a volume for the cache at /var/cache/image-garden. pkgproxy isn't inside; you point the container at one with PKGPROXY_URL. spread isn't either, which is why the GitLab CI components build their own image on top of this one.
Details and sources
Details
- The first build stage builds QEMU from the release tarball, checked by its sha256, with the guestfwd patch, for
x86_64,aarch64,riscv64,s390x,ppc64andloongarch64(Dockerfile:5-54). - The final image installs
ovmf,swtpm,curl,make,xorriso,xz-utilsandgit, setsGARDEN_CACHE_DIR=/var/cache/image-gardenand declares that directory a volume (Dockerfile:73-104). It has no spread, no pkgproxy and no entrypoint. - The README's run example:
docker run --device /dev/kvm --volume $HOME/.cache/image-garden:/var/cache/image-garden image-garden:latest, and the same with podman (README.md:342-382). - CI builds the image on an x86_64 and an aarch64 runner and, for a tag, publishes one image with both, tagged with the tag and
latest(.gitlab-ci.yml:1231-1278). - The GitLab CI components build on this image and add spread; see the CI projects.
04 Distribution packages
Packages for Arch Linux (AUR), Debian, openSUSE and Fedora use the host's QEMU, firmware and swtpm. pkgproxy comes from PKGPROXY_URL; downloads go to $XDG_CACHE_HOME/image-garden.
Several distributions package image-garden: Arch Linux in the AUR, Debian, openSUSE and Fedora. Install it the way you install anything else there. The difference from the snap and the container is that a package uses what your distribution already has: its QEMU, its firmware, its swtpm. So the architectures you can boot are the emulators you've installed. pkgproxy isn't bundled; name one with PKGPROXY_URL and guests reach it over QEMU's ordinary network. spread, if you want it, is a package of its own. Downloads go to image-garden's folder in your home cache directory. The rules, the systems and the commands are the same as everywhere else.
Details and sources
Details
- The README links packages for Arch Linux (AUR), Debian, openSUSE and Fedora; its table says a package uses the system's QEMU, EFI firmware and swtpm, spread is a system package, pkgproxy works "With
PKGPROXY_URL", and the cache is$XDG_CACHE_HOME(README.md:96-112). - Outside the snap,
GARDEN_CACHE_DIRis$XDG_CACHE_HOME/image-garden, andXDG_CACHE_HOMEdefaults to~/.cache(mk/000-garden.mk:9-12). - With
PKGPROXY_URLset, the host is resolved to an IPv4 address when make runs and guests reach it through QEMU's user network; noguestfwdis added (mk/010-qemu.mk:20-44). The snap's socket modes need the patched QEMU; a package never uses them. - The emulator is
qemu-system-<arch>fromPATH(mk/010-qemu-x86_64.mk:4); a distribution QEMU does not carry the guestfwd patch. - Distribution packages may be older than the upstream release (the maintainer's statement).
05 Building from source
make && sudo make install builds image-garden.mk and installs it with the command under /usr/local. The host needs curl, xorriso, qemu-img and the qemu-system-* emulators.
If your distribution has no package, or you want a commit newer than any release, build it yourself. In a checkout of the tree, run make, then sudo make install. make turns image-garden's list of systems into rules and joins them into image-garden.mk, and install puts that file under /usr/local, next to the image-garden command. You bring the tools: curl, xorriso, qemu-img, and QEMU's system emulators for the architectures you want. The Ubuntu Core systems with a TPM also need swtpm and the ovmf firmware. Each tool is looked for only when a step needs it, so a missing one stops make at the step that uses it.
Details and sources
Details
prefix ?= /usr/local;make installputsimage-gardenin$(bindir)with@PREFIX@,@INCLUDEDIR@,@DOCDIR@and@VERSION@filled in,image-garden.mkin$(includedir), the README and NEWS files in$(datarootdir)/doc/image-gardenand the man page in$(man1dir);includediranddatarootdirdefault fromprefixbut can be set on their own (Makefile:3-46).image-garden.mkisdata/000-systems.mk, the sortedmk/*.mkand the sorteddata/050-*.gen.mkjoined, each.gen.mkwritten byrulegen.pyfrom one.ini(Makefile:48-64).- The README asks for
curl,qemu-system-x86_64,qemu-system-aarch64,qemu-system-riscv64,qemu-system-s390x,qemu-system-ppc64,qemu-system-loongarch64,qemu-imgandxorriso, "or the emulators of the architectures you use", andswtpmwith theovmfSecure Boot firmware for the TPM systems (README.md:114-126). xorrisoandcurlare$(error ...)when missing (mk/000-garden.mk:20-21), as isqemu-img(mk/010-qemu.mk:3); a missingqemu-system-x86_64is a$(warning ...)(mk/010-qemu-x86_64.mk:4), and the recipe that runs it fails later (derived).make checkruns the project's own checks (shellcheck, mypy, the rulegen and download tests).
Read more
- A source build, what the host needs, how image-garden.mk is put together.
XORRISO,CURLandQEMU_IMGare set with?=(mk/000-garden.mk:20-21, mk/010-qemu.mk:3), so each is looked for only when the first step that uses it runs;image-garden make list-systemsworks without any of them (run at v0.8.0 for the nat-deps deck). See what the host needs.
06 How current each one is
The snap and the container are built from the tree on every release tag; the snap's edge channel is built nightly. Distribution packages may be older than upstream. image-garden version and image-garden news tell you what you have.
So how new is what you get? The snap and the container are built from the image-garden tree itself. A release tag becomes a stable snap, and a container image tagged with the version and with latest. The snap's edge channel is built every night from the newest commit. Distribution packages follow their distribution's own schedule, and the maintainer's word on this is plain: packages such as Debian's and Fedora's may be older than the upstream release. To check what you have, run image-garden version, and image-garden news prints what changed in it.
Details and sources
Details
- The snap's version comes from
git describe: a commit that is exactly a tag gets that version and gradestable, any other commitTAG+gitN.HASHand gradedevel(snap/snapcraft.yaml:271-299). - The snap is published through Launchpad by the
snap-edgeandsnap-stablejobs; a nightly schedule exists only to build edge (.gitlab-ci.yml:26-33, .gitlab-ci.yml:128-129). - The container is published for a tag only, as the tag and as
latest(.gitlab-ci.yml:1257-1278). - Distribution packages, such as Debian's and Fedora's, may be older than the upstream release: the maintainer's statement, not in the source.
image-garden versionprintsimage-garden VERSION;image-garden news [N]prints the last N "Changes in" sections of NEWS, NEWS.snappy and NEWS.docker, those present in the install (image-garden:909-942). The snap leaves out NEWS.docker, the container NEWS.snappy.
Read more
07 Where to go from here
Next: the snap, the container, and native packages and source builds, each in its own district.
That's the choice: the snap brings the most, the container carries the same QEMU into any runner, and a package or a source build uses what your system already has. Each has its own district on the map. The snap deck shows what the install adds and what confinement changes. The container deck shows how to run it on your project. And the native packages district covers the distribution packages, a source build, and the tools your host needs.
Details and sources
Read more
Basis of the statements on this page
The comparison table of the README of image-garden, at the commit this map describes (README.md:96-106), checked against the snap's snapcraft.yaml, the Dockerfile and the Makefile ("code"). The age of distribution packages is the maintainer's statement.
The three ways in, side by side
| Snap | Container | Native package or source | |
|---|---|---|---|
| Where | Snap Store | container registries | Arch (AUR), Debian, Fedora, openSUSE; or make && make install |
| How current | follows upstream releases | follows upstream releases | distribution packages, such as Debian and Fedora ones, may be older than upstream |
| QEMU | built by the snap, one component per architecture | built into the image | your distribution's |
| guestfwd unix socket patch | yes | yes | no |
| Architectures | x86_64, aarch64, riscv64, s390x, ppc64, loongarch64 | the same six | what your QEMU has |
| UEFI firmware | in the QEMU components | built with QEMU, plus the ovmf package | system packages |
| swtpm, for +tpm systems | optional swtpm component | included | system package |
| spread | the spread component, added at install; spread-plus on demand | no | system package |
| pkgproxy | bundled, or snap set image-garden pkgproxy=… | PKGPROXY_URL | PKGPROXY_URL |
| virtiofsd | bundled, run as image-garden.virtiofsd | no | system package |
QEMU's -snapshot scratch | ~/snap/image-garden/common/tmp, on disk (qemu-var-tmp:9-20) | /var/tmp inside the container | /var/tmp, unless TMPDIR says otherwise |
| Cache | ~/snap/image-garden/common/cache | a volume at /var/cache/image-garden | ~/.cache/image-garden |
The first command in each
| Install | Command |
|---|---|
| Snap | snap install image-garden; more QEMUs with snap install image-garden+qemu-aarch64, swtpm with snap install image-garden+swtpm |
| Container | docker run --device /dev/kvm --volume $HOME/.cache/image-garden:/var/cache/image-garden image-garden:latest image-garden make SYSTEM.run (or podman run) |
| Distribution package | your distribution's package manager |
| Source | make && sudo make install, into /usr/local unless prefix= says otherwise |
Every install then answers image-garden version and image-garden news.
Where to go
- The snap and its components and pkgproxy setting.
- The container and how to run it.
- Distribution packages, a source build and what the host needs.
Roads from here
SNAP · snap-only features
- The image-garden snap — what the snap installs and what strict confinement changes
CONTAINER · OCI image
- Running image-garden in a container — run the container on your own project, with /dev/kvm and a cache volume
- The OCI container — what the container image is built from
NATIVE · packages
- Distribution packages — the distribution packages and where to find them
- Installing from source — build and install image-garden from the tree
- What a native install needs from the host — the tools and emulators a host needs without the snap or the container