Layers
How an app's root filesystem is built, and what runs in it.
The root filesystem an app sees is a stack. Top to bottom:
the volume writable; the only thing backed up
layers[n-1]
… the layers in desired.json, in the order listed
layers[0]
Debian the guest image nibrunner ships; always the bottomLayers
A layer names content by its digest, either in the artifact store or in a public OCI registry:
kind | Contents |
|---|---|
executable | One program. The host packs it into an image at destinationPath. |
filesystem | A squashfs or ext4 image. Attached as uploaded. |
oci | A Linux amd64 image from an artifact-store archive or public registry. |
"layers": [
{ "kind": "filesystem", "digest": "<sha256, lowercase hex>", "objectKey": "base/runtime" },
{ "kind": "executable", "destinationPath": "/app/server", "digest": "<sha256, lowercase hex>", "objectKey": "my-server" }
]Downloaded layers are cached by digest. Apps on the same host share cached layers.
The volume
The volume is the writable top of the stack. Every write goes there and persists. Nothing else persists. An export contains the volume, the environment, and the original crontab when the app has registered cron jobs, never the contents of a layer. If a layer and the volume both hold a file at the same path, the volume's copy wins.
What runs
The guest's init runs config.command once the root is assembled: program with args, in
workingDirectory, with environment, as uid 65534.
"command": {
"program": "/app/server",
"args": ["--port", "3000"],
"workingDirectory": "/app",
"environment": { "DATABASE_URL": "sqlite:///app/data.db" }
}If no layer contains the working directory, the host creates it and gives it to uid 65534. The
program can write to the working directory and to /tmp. It is chrooted into the stacked root,
so it cannot reach the guest's init, the raw volume, or the host.
From an OCI image
Use kind: "oci" for a Linux amd64 Docker or OCI image. The host downloads the image, verifies
its manifests and layers, and prepares its filesystem. Docker is not needed on the host.
| Source | Field | What digest identifies |
|---|---|---|
| Public image registry | repository | The image manifest or multi-platform index. |
| OCI archive in the artifact store | objectKey | The whole archive. |
Set exactly one of repository or objectKey. Digests are lowercase SHA256 hex, without the
sha256: prefix. Add the layer to your instance in desired.json.
From a registry
Name the registry and full repository path. This example pins Docker's official BusyBox
1.37.0-musl image:
"layers": [
{
"kind": "oci",
"repository": "docker.io/library/busybox",
"digest": "5cec3fc171c87218698e85a52af7087de727372aae264a787b8112901a5b0092"
}
]The host selects Linux amd64 from a multi-platform index. Registry pulls require HTTPS and public access. Private repositories and tags are not supported.
From an archive
Export your Dockerfile with a Buildx builder that supports the OCI exporter, such as the
docker-container driver:
docker buildx build --platform linux/amd64 --output type=oci,dest=app.oci.tar .Copy the archive to the host. For the default local artifact store:
set -euo pipefail
digest=$(sha256sum app.oci.tar | cut -d ' ' -f 1)
install -D -m 0644 app.oci.tar "/var/lib/nibrunner/artifact-store/$digest"
printf '%s\n' "$digest"For an object store, upload the archive to artifacts.store_url under a key of your choice.
Set objectKey to that key and digest to the archive's SHA256:
"layers": [
{ "kind": "oci", "objectKey": "<store key>", "digest": "<archive sha256>" }
]Use the OCI exporter shown above. Archives from docker save or docker export are not supported.
Image configuration
The image supplies files. Set how the app runs in desired.json. Copy any image defaults your
app needs, including those inherited from its base image:
| Image setting | nibrunner setting |
|---|---|
ENTRYPOINT, CMD | config.command.program and args. Preserve the entrypoint and its arguments, including wrapper scripts. Use an absolute program path. |
WORKDIR | config.command.workingDirectory. Use / if the image has none. |
ENV | config.command.environment. Include inherited variables the app needs. |
EXPOSE | config.httpPort or config.ports. |
HEALTHCHECK | config.healthCheck. Docker's check is not imported. |
USER | The app runs as uid/gid 65534. Files must be readable and programs executable by that account. |
VOLUME | The app uses its nibrunner volume. Image volume declarations and host mounts are not imported. |
The server must listen on 0.0.0.0. Writable directories must allow uid 65534 access. Entrypoints
that require root or Docker-specific mounts need adapting.
Limits
OCI archives must contain one Linux amd64 image. Both sources allow at most 128 image layers, 1 GiB of decoded data, 100,000 filesystem entries, and 4 MiB of JSON metadata. Registry downloads also allow at most 1 GiB of blobs.
Device nodes, FIFOs, sparse files, LIBARCHIVE extended attributes, and hard links to symbolic
links are refused. Supported extended attributes use the SCHILY.xattr.* tar convention.
Update the image
Upload a new archive or choose a new registry digest, then update the layer, deploymentId, and
document revision. Keep volumeId to retain the app's data. Files already written to the
volume take precedence over files in the new image.