Publishing nodes
A container node builds into a single Apptainer .sif image. Peppy can push that image to an OCI registry (GitHub Container Registry, Docker Hub, or a private registry) so other machines with that oci repository can download the image instead of rebuilding it from source. This saves minutes per build, especially on smaller devices like a Raspberry Pi.
Only container nodes can be published. Process nodes (build_cmd / run_cmd) always build locally.
Set up a repository
Section titled “Set up a repository”-
Choose one OCI repository to store your published nodes, such as
oci://ghcr.io/acme/peppy-nodes. One repository holds nodes for all Peppy versions because each artifact gets its own tag (see Registry layout). -
On the publishing machine, set
publish_repositoryin~/.peppy/conf/peppy_config.json5and restart the daemon:publish_repository: "oci://ghcr.io/acme/peppy-nodes", -
Log in to the registry on every publishing machine and on any machine that pulls from a private repository (see Registry credentials).
-
On machines that should pull prebuilt images, add the OCI repository with a lower
idthan your source repositories (--top) and refresh:Terminal window peppy repo add oci://ghcr.io/acme/peppy-nodes --toppeppy repo refresh
Because artifacts are tied to a specific Peppy release version, only release builds of Peppy can publish or pull OCI node artifacts. Non-release builds reject both operations with an explanation.
Registry credentials
Section titled “Registry credentials”Peppy reads registry credentials from Apptainer’s auth file chain: $APPTAINER_AUTH_FILE if set, otherwise ~/.apptainer/docker-config.json (from apptainer registry login) if it exists, otherwise ~/.docker/config.json (from docker login). Log in with either tool:
docker login ghcr.ioapptainer registry login --username <user> docker://ghcr.ioFor a given registry, Peppy resolves credentials in this order:
- The helper named in
credHelpersfor that registry. - The default helper named in
credsStore. - The registry’s entry under
auths(username/password, token, oridentitytoken).
Credential helpers run as docker-credential-<name> on the daemon’s PATH. Without credentials, Peppy sends unauthenticated requests (which works for pulling from public repositories). The auth file is re-read before every pull and push, so new logins take effect without restarting the daemon.
Pushing requires write permission (for GitHub Container Registry, a personal access token with the write:packages scope).
Publish a node
Section titled “Publish a node”peppy node publish <name>:<tag> [--platforms <platform>,...] [--idle-timeout <secs>] [--max-timeout <secs>] [--force]The node must already be added to the stack (peppy node add <name>:<tag>). The daemon builds the node for the host platform (just like peppy node build) and pushes the .sif to publish_repository under the tag <name>.<tag>.<peppy version>.linux-<arch> (for example, camera.v1.v0.32.0.linux-amd64).
| Flag | Effect |
|---|---|
--platforms | Additional comma-separated platforms to build and push alongside the host platform (linux/amd64, linux/arm64). See Build for another architecture. |
--idle-timeout | Per-platform build idle timeout in seconds (same as peppy node build). |
--max-timeout | Per-platform maximum build duration in seconds. Platforms build sequentially, so total time is up to this value times the platform count. |
--force | Cancel any running build of the node and start publishing. |
The checks
Section titled “The checks”Before building anything, peppy node publish runs these preflight checks in order. The first failure aborts immediately with a fix message:
publish_repositoryis configured on the daemon.- Peppy is a release build.
- The node is a container node (process nodes are refused with a link to the container guide).
- The node did not come from an
ocirepository (no local source exists to build). - Every
--platformsentry islinux/amd64orlinux/arm64(validated locally by the CLI). - The registry accepts a push using this machine’s credentials.
- Cross-architecture prerequisites are present for any non-host platform in
--platforms: QEMU system emulator and UEFI firmware are installed, Peppy has Lima and Apptainer for that architecture, theapptainer.defbase image supports that platform, and (for Python nodes) Peppy includes thepeppylibnative extension for that platform. Release builds bundle Lima, Apptainer, andpeppylibfor all supported Linux platforms. - Any existing tag in the registry for a target platform has the same source digest as this node. Tags are immutable and never overwritten.
The source digest is the SHA-256 of the node’s staged tree (excluding vendored peppylib for Python nodes), so identical sources produce the same digest on every machine and platform. The command prints it (e.g., Source digest of `camera:v1`: sha256:9c1e...).
- Same digest already published: The platform is skipped and reported as
already published. - Different digest on the same tag: The publish fails and prints both digests. Bump the node tag (e.g.,
v2) or publish under a new Peppy version (each Peppy release uses distinct tags).
What the command prints
Section titled “What the command prints”The command streams build output plus hashing/push progress (every 1% and at least once every 10 seconds while transferring), then prints one summary line per platform:
linux/amd64: pushed camera.v1.v0.32.0.linux-amd64 (sha256:4b7f...)linux/arm64: already published as camera.v1.v0.32.0.linux-arm64Published node camera:v1If any requested platform fails to publish, the command exits with an error reporting how many platforms failed.
Build for another architecture
Section titled “Build for another architecture”Pass --platforms to build for the other Linux architecture alongside the host’s (--platforms linux/arm64 on amd64, or --platforms linux/amd64 on arm64). Listing the host’s own platform does not build it twice.
Cross-architecture builds run inside a persistent Lima VM using QEMU emulation (peppy-aarch64 for linux/arm64, peppy-x86_64 for linux/amd64) on both Linux and macOS. Peppy bundles Lima and Apptainer for both architectures, but you must install QEMU and UEFI firmware on the host:
| Operating system | For linux/arm64 on an amd64 machine | For linux/amd64 on an arm64 machine |
|---|---|---|
| macOS | brew install qemu | brew install qemu |
| Debian, Ubuntu | sudo apt install qemu-system-arm qemu-efi-aarch64 | sudo apt install qemu-system-x86 ovmf |
| Fedora | sudo dnf install qemu-system-aarch64-core edk2-aarch64 | sudo dnf install qemu-system-x86-core edk2-ovmf |
| Arch Linux | sudo pacman -S qemu-system-aarch64 edk2-aarch64 | sudo pacman -S qemu-system-x86 edk2-ovmf |
Emulated builds are significantly slower than native builds. Each platform builds from its own copy of the staged tree with per-architecture build caches. Your definition file’s base image must support the target platform (peppybot/rust-cargo-base and peppybot/python-uv-base support both).
Publish the nodes of a stack
Section titled “Publish the nodes of a stack”peppy stack build <launcher> --publish [--platforms <platform>,...]Each machine in the stack builds its assigned container nodes and pushes their .sif images to the invoking daemon’s publish_repository, authenticating with each machine’s own registry credentials. Passing --platforms (which requires --publish) builds and pushes those additional platforms on each machine as well.
Before any build starts, the invoking daemon runs checks 1, 2, and 6 locally, and every other participating machine verifies registry push access during reservation. Any failure there aborts the whole command and names the machine. Per-node/per-platform checks do not abort the rest of the stack: skipped items are logged in the final report while other nodes continue:
Publish report: camera:v1@cn-atlas linux/amd64: pushed camera.v1.v0.32.0.linux-amd64 (sha256:4b7f...) camera:v1@cn-atlas linux/arm64: not published: the base image docker.io/acme/camera-base:1.2 of apptainer.def has no linux/arm64 planner:v2@cn-atlas: not published: process node arm_driver:v1@cn-pi: not published: comes from the oci repository oci://ghcr.io/acme/peppy-nodesIf any container node platform fails to publish, the command finishes printing the report and exits with code 4 (failed goal). Process nodes and nodes sourced from an oci repository appear in the report without causing an error.
Registry layout
Section titled “Registry layout”One OCI repository holds all published nodes. Each artifact represents one (node, Peppy version, platform) tuple:
- Tag:
<node name>.<node tag>.<peppy version>.linux-<arch>(amd64orarm64). Registries limit tags to 128 characters, so nodes whose tag exceeds 128 characters cannot be published. - Manifest: OCI image manifest with artifact type
application/vnd.peppy.node.v1and empty configapplication/vnd.oci.empty.v1+json. - Layer 1 (
.sifimage): Media typeapplication/vnd.sylabs.sif.layer.v1.sif. - Layer 2 (
peppy.json5manifest): Media typeapplication/vnd.peppy.node.manifest.v1+json5.peppy repo refreshreads this layer alone without downloading the.sif. - Annotations:
bot.peppy.node.name,bot.peppy.node.tag,bot.peppy.version,bot.peppy.platform, andbot.peppy.source-digest. Nodes sourced from agitrepository also includebot.peppy.source.url,bot.peppy.source.commit, andbot.peppy.source.path.
Peppy never deletes or overwrites tags. Remove obsolete Peppy versions using your registry’s own tools.