Building a site
Read this when you turn your own image into a site. The Dockerfile describes the app.
Labels in it, or flags on snowglobe build, tell snowglobe how to snapshot it.
Describe it in the Dockerfile
Labels let an image describe itself. A flag on the command line overrides its label. This is the Python demo's whole Dockerfile:
FROM alpine:3.24.2
RUN apk add --no-cache python3
CMD ["python3"]
LABEL snowglobe.title="Python in the browser" \
snowglobe.ready=">>> " \
snowglobe.exercise='["import json, re, collections", "import asyncio; asyncio.run(asyncio.sleep(0))"]'
Every flag and its label are in the build flags table.
When the snapshot is taken
snowglobe boots the image until the app is ready, then saves the whole machine. Visitors restore that snapshot instead of booting Linux.
- With
--ready TEXT(orsnowglobe.ready), the app is ready once it prints that text. Use its prompt. - Without it, the app counts as ready once its terminal has been quiet for 5 seconds.
--cmd swaps the program without touching the image. It also drops the image's
ready and exercise labels, which belonged to the image's own command.
Freed memory stays out of the snapshot
Memory the guest freed would still hold what it held: a package manager's caches, a compiler's
work, a secret a setup step read. The guest's kernel zeroes each page as it frees it
(init_on_free), so none of that reaches the snapshot. A site with a kernel also has free page
reporting: the kernel reports the free memory to the machine in 2 MiB blocks, and the machine gives
those pages back. The build lets the guest idle a few seconds before saving, so the last of it is
reported. The guest keeps all of its memory: it can use those pages again at any time.
A snapshot restores only onto the devices it was saved with, so sites built before this have no such device and restore as they are. Rebuild a site to make its snapshot smaller.
Exercises and the warm pack
The guest fetches its files on demand. To hide that wait, every site preloads a
warm.pack in the background. snowglobe fills it by measuring, not guessing, with what a
restored machine reads, in the order it first reads it:
- Restore reads: the build drops the guest's file cache before the snapshot, as a visitor's machine starts. After saving it, snowglobe lets the machine run on its own for a few seconds and records what its services read.
- Exercise reads: then it types each
--exercisecommand into the app and records what it reads. These are the files a visitor's first commands would otherwise wait for. A command is done once the app prints its prompt again and goes quiet. - Pattern: anything matching
--warm REGEX, for files no exercise touches, after the rest.
What only booting read stays out of the pack: the restored machine has it in memory already, or
never reads it again. A site with no exercises (or built with --sandbox) packs its boot
reads after the rest, the best guess there is.
The page reads the pack as it streams in, so the files the guest needs first arrive first. A read of a file the pack brings soon waits for it; one far off (a visitor whose first command isn't the build's) is fetched on its own, and the pack holds back while the guest waits on such fetches, so they have the bandwidth. Files the machine's own cache lets go come again from the pack, or from the copy the page keeps of files it fetched on their own, never from the network a second time.
Each build prints a breakdown and writes warm-report.json: what the restored machine read
settling, what each exercise read first, what only booting read, the pattern's files and the files
never read.
An app used over the network, not through its console, can be warmed from real traffic instead. Record its reads while something talks to it, then add them to the pack:
snowglobe run dist --name api --detach -p 5000:5000 --record-reads api-reads.json
npm test # anything that talks to 127.0.0.1:5000
snowglobe stop api && snowglobe warm dist api-reads.json
CPUs and memory
--memory MBsets the guest's RAM (512 by default).--cpus N(1 to 8) gives it more CPUs. Each runs in its own Web Worker on shared memory, which helps programs that use them.- A build boots on at least 4 CPUs (
--build-cpus) and takes the extra ones offline before the snapshot.
Browsers only share memory between workers on a cross-origin isolated page, and a static host can't declare one. So a site on several CPUs ships a small service worker that reloads the page once on the first visit. Such a site can't run inside another page's frame.
Services in the image
The guest boots with BusyBox's init and no service manager, so the app is ready seconds
after the kernel starts.
- Services an image enables for OpenRC do not start. Start them from the command, as the Postgres and Elixir examples' start scripts do.
- Slow first-time setup (an
initdb, migrations) belongs in a DockerfileRUN. There it runs at native speed instead of in emulation.
Building without Docker
--builder native (or SNOWGLOBE_BUILDER=native) builds from either:
- an image reference, pulled from its registry, or
- an image archive:
docker save, or an OCI layout from buildah, kaniko or anything else.
Nothing runs at build time either way. The image's layers are flattened, the prebuilt kernel and boot
files go on top, and snowglobe-vm boots and snapshots it on your machine.
snowglobe build python:3.13-alpine --builder native --ready '>>> ' docker save my-app:latest -o my-app.tar # on a machine with a builder snowglobe build my-app.tar --builder native # anywhere else
Hosting several sites, and installing them
snowglobe pool <dir>lets every site under a directory share one blob store. Blobs are named by content, so sites built on the same base share many, and a visitor's second site reuses what their browser cached.snowglobe pwa <site>makes a site an installable app that keeps working offline once it has run. It adds a manifest, icons and a service worker that caches the page, the machine and every file the run fetched. The page asks for its build's own files (the snapshot, the filesystem tree, the warm pack, the machine and its scripts) with that build's version (?v=), so a repeat visit gets them from that cache instead of downloading them again, and a newer build's page asks for other URLs and never gets an older build's copy. Run it afterpool.
Next: give the guest a network on Networking, or run the site without a browser on Running outside a browser.