Guides

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 bottom

Layers

A layer names content by its digest, either in the artifact store or in a public OCI registry:

kindContents
executableOne program. The host packs it into an image at destinationPath.
filesystemA squashfs or ext4 image. Attached as uploaded.
ociA 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.

SourceFieldWhat digest identifies
Public image registryrepositoryThe image manifest or multi-platform index.
OCI archive in the artifact storeobjectKeyThe 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 settingnibrunner setting
ENTRYPOINT, CMDconfig.command.program and args. Preserve the entrypoint and its arguments, including wrapper scripts. Use an absolute program path.
WORKDIRconfig.command.workingDirectory. Use / if the image has none.
ENVconfig.command.environment. Include inherited variables the app needs.
EXPOSEconfig.httpPort or config.ports.
HEALTHCHECKconfig.healthCheck. Docker's check is not imported.
USERThe app runs as uid/gid 65534. Files must be readable and programs executable by that account.
VOLUMEThe 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.

On this page