Bake
Most of a create’s wait is the repo’s own setup: dependency installs, container image builds, seeds. A toolchain-only image can’t help with any of that, so a bake prebuilds the repo:
pier bake # one throwaway instance: harnesses + .pier/bake.sh, then your # checkout (HEAD) with .pier/setup.sh run to completion, imagedpier bake returns as soon as the bake instance is done. Saving the image,
which copies the bake disk into image storage, often takes longer than the
bake itself and finishes in the background. Until it does, sessions keep
starting from the previous image. Once it’s saved, the new image is
recorded, every older image of the repo is deleted, and the repo’s
warm pool fills from it.
Sessions launched from the image find the checkout and everything setup
left around it (installed dependencies, virtualenvs, the docker build cache,
built images, volumes) already on disk. The bootstrap fetches only what
changed, moves the checkout to your branch, and .pier/setup.sh re-runs
warm: cache hits instead of a cold install. On AWS the restored volume is
also hydrated at a provisioned rate right after launch, a few cents per
create, so the first commands don’t stall on lazily-loaded snapshot blocks.
pier setup bakes a repo that has a .pier/bake.sh without asking, since
its sessions need those toolchains, and offers the bake for any other repo.
With the Fast profile, a baked repo also keeps a warm pool
of one set-up session, so the next create skips setup entirely.
One image, with or without the repo
Section titled “One image, with or without the repo”Each repo has one session image. The image contents setting decides what a bake puts in it: toolchains plus the prebuilt repo (the default), or toolchains only, for repos whose state should stay out of images. Override it for one bake:
pier bake --toolchain-only # harnesses and .pier/bake.sh toolchains onlypier bake --with-repo # prebuild the repo, whatever the setting saysSecrets stay out
Section titled “Secrets stay out”Before imaging, the bake scrubs everything the create cargo delivered:
harness auth, tokens, the MCP seed, untracked and .pier/include files,
containers (their config holds env_file values), setup logs. Every create
pushes those fresh, so scrubbing costs no speed. What setup derives from
secrets, such as an env value compiled into a build or a seeded database, is
the repo’s to keep out. Anyone who can launch the image can read its disk.
Freshness
Section titled “Freshness”Freshness is manual: re-run pier bake when dependencies drift enough that
the warm re-run gets slow. Images are keyed to the repo, so one project’s
toolchain never bleeds into another’s. A bake deletes every older image of
its repo, and pier teardown sweeps them all by tag.
Images carry their repo and owner as tags, and the cloud is their record:
the config only caches which image a repo uses. A lost config never orphans
an image. pier setup and creates pick the newest one back up.
Cloud-init is guarded and identical on stock and baked images. Every install
step is a no-op when the image already has it. For a repo without
.pier/bake.sh, baking is an optimization. A repo with one requires an
image.
Rebake reminders
Section titled “Rebake reminders”pier never rebakes on its own. With bake reminders on (the Fast and Lean
profiles), it says when a bake would make sessions start faster, and only
states facts: the repo has no image yet, its image is older than the
reminder age (30 days by default), or .pier/setup.sh or .pier/bake.sh
changed since the bake. Reminders show after a create (at most once a day
per repo), as a dot on the app’s Repos tab, and in pier repos.
- A bake hook requires an image. A repo with a
.pier/bake.shgets no sessions until it’s baked:pier <branch>refuses rather than launching the stock image, where.pier/setup.shwould fail on missing toolchains. - On AWS, bake needs three extra permissions:
ec2:CreateImage,ec2:DeregisterImageandec2:DeleteSnapshot.