Build OCI And UEFI Images

Use this guide when you want image forms beyond the QEMU -kernel bundle.

Build The OCI Inspection Image

ct run oci-image

The local image name is:

den:dev

This target packages the staged rootfs directly. It does not require the Buildroot kernel or initramfs.

Run the smoke:

ct run oci-smoke

The smoke starts the arm64 image through Docker/OrbStack and checks:

  • /etc/os-release,

  • the current Den generation,

  • the conda-provided bash in /run/current-system/sw/bin/bash.

Open an interactive shell:

docker run --rm -it --platform linux/arm64 den:dev

Use --platform linux/amd64 instead when den:dev was built from the linux-64 Den target.

Inside that shell, conda is on PATH:

conda --version
conda config --show channels default_channels channel_priority

The OCI image bakes in /etc/conda/.condarc with conda-forge, strict channel priority, and an empty default_channels list. That keeps ordinary in-container conda commands away from Anaconda’s default channels unless a user deliberately overrides the configuration.

This image is for inspection and CI-style userland checks. It is not a VM disk and does not exercise the kernel, initramfs, GRUB, or systemd as PID 1.

Use The OCI Image As An Application Base

The same local image can be used as a base for application containers:

FROM den:dev

RUN conda create \
      --yes \
      --prefix /opt/app \
      --override-channels \
      --channel conda-forge \
      python=3.12 \
      <packages> && \
    conda clean --all --force-pkgs-dirs --yes

ENV PATH=/opt/app/bin:/opt/den/bin:/run/current-system/sw/bin:/bin:/usr/bin:/sbin:/usr/sbin

See the starter examples:

This is different from running Docker inside a booted Den VM. Den does not yet package or smoke-test Docker, Podman, cgroups, or a container-host policy for a booted Den system.

Build The UEFI Disk Image

ct run uefi-image

The outputs are:

build/artifacts/den-uefi-aarch64.raw
build/artifacts/den-uefi-aarch64.qcow2
build/artifacts/den-uefi-aarch64.receipt.json

The task is named uefi-image because this is the disk form needed before provider images become possible. The current artifact is still a QEMU UEFI prototype. It includes a small Den NoCloud-compatible seed handler and first-boot rootfs growth, but it does not query provider metadata services or include provider-specific image metadata.

Smoke The UEFI Disk

ct run uefi-image-smoke

This target builds the disk, creates a smoke copy under build/uefi-image-smoke, creates a FAT cidata seed image, boots with AArch64 UEFI firmware in QEMU, waits for den-server-smoke.service, and expects the guest to power off.

The success marker is:

Den systemd: server smoke complete

Boot The UEFI Disk With Homebrew QEMU

If QEMU was installed with Homebrew on Apple Silicon, the firmware and emulator usually resolve through:

QEMU_BIN="$(brew --prefix qemu)/bin/qemu-system-aarch64"
QEMU_EFI="$(brew --prefix qemu)/share/qemu/edk2-aarch64-code.fd"

Boot the raw disk:

"$QEMU_BIN" \
  -M virt \
  -cpu cortex-a57 \
  -m 2048 \
  -nographic \
  -no-reboot \
  -net none \
  -bios "$QEMU_EFI" \
  -drive if=none,id=den_disk,file=build/artifacts/den-uefi-aarch64.raw,format=raw \
  -device virtio-blk-pci,drive=den_disk

For the deterministic smoke path, use ct run uefi-image-smoke; it appends den.systemd=smoke and powers off automatically.

Boot The UEFI Disk Through The Builder Container

The default local smoke target runs QEMU in the optional builder container. If you want a manual container boot of the raw disk, build that image first:

docker build -f docker/buildroot-builder.Dockerfile -t den-buildroot-builder:2026.02 .

Then run:

docker run --rm -it \
  -v "$PWD:/work" \
  -w /work \
  den-buildroot-builder:2026.02 \
  bash -lc 'qemu-system-aarch64 \
    -M virt \
    -cpu cortex-a57 \
    -m 2048 \
    -nographic \
    -no-reboot \
    -net none \
    -bios /usr/share/qemu-efi-aarch64/QEMU_EFI.fd \
    -drive if=none,id=den_disk,file=/work/build/artifacts/den-uefi-aarch64.raw,format=raw \
    -device virtio-blk-pci,drive=den_disk'

Convert To Another Disk Format

The uefi-image target already creates qcow2. To create the current VDI handoff artifact for VirtualBox experiments, run:

ct run virtualbox-image

The output is:

build/artifacts/den-virtualbox-aarch64.vdi

This target uses qemu-img, so it does not require VirtualBox to be installed on the host. The VDI is not boot-smoked yet.

You can also convert manually with VBoxManage:

VBoxManage convertfromraw build/artifacts/den-uefi-aarch64.raw \
  build/artifacts/den-uefi-aarch64.vdi \
  --format VDI

The converted VDI is not a supported Den target yet. The current boot smoke uses QEMU virt.

Run Image Checks In GitHub Actions

The Images workflow consumes the hosted Den package channel, builds the Buildroot early boot layer, rootfs image, QEMU bundle smoke, and UEFI disk smoke directly on blacksmith-8vcpu-ubuntu-2404-arm. It does not compile Den-owned package recipes; package builds and compiler caching live in den-forge.

The hosted-channel image path has passed end to end on GitHub Actions: Buildroot, rootfs assembly, rootfs image verification, QEMU boot bundle smoke, and UEFI disk smoke all consumed https://packages.den-os.org/den-forge/den-2026.6.

The workflow uses GitHub Actions caches for:

  • the cx package cache under ~/.conda/express/pkgs,

  • Buildroot source under build/buildroot-src,

  • Buildroot output under build/buildroot-output.

On Blacksmith runners, the normal actions/cache steps use Blacksmith’s colocated cache service without changing the workflow cache actions.

The official conda-express setup-cx action tolerates a restored cx package cache before bootstrap, so cache hits do not make cx bootstrap fail on a non-empty runtime directory.

It uses workflow artifacts only to pass finished image outputs between jobs:

  • den-early-boot-aarch64,

  • den-rootfs-aarch64.

Rootfs assembly uses the hosted Den package channel at https://packages.den-os.org/den-forge/den-2026.6 for the conda workspace lock and install.

Trigger it manually from GitHub Actions when you want the full image smoke path:

gh workflow run images.yml --ref main