# Use An Existing Image Use this guide when someone already has a Den artifact and wants to boot or inspect it without rebuilding Den. The current local artifacts are: ```text den-qemu-aarch64.tar.zst den:dev den-uefi-aarch64.raw den-uefi-aarch64.qcow2 ``` In this repository, locally generated file artifacts normally live under: ```text build/artifacts/ ``` Choose the entry point based on what you want to test: - use the QEMU bundle to test the direct `-kernel`/`-initrd` boot path, - use `den:dev` to inspect the rootfs in Docker/OrbStack, - use the raw/qcow2 disk to test the GRUB-backed UEFI boot path in QEMU. The raw ext4 file, `den-rootfs.ext4`, may exist in `build/artifacts/` and is part of the bundle workflow. It is not the recommended standalone entry point because it still needs the matching kernel, initramfs, QEMU command line, and boot metadata. If you only have `den-rootfs.ext4`, first recreate or obtain the matching bundle. The bundle keeps the rootfs, Buildroot kernel, Buildroot initramfs, QEMU launcher, manifest, and checksums together. ## Use The QEMU Bundle The bundle normally lives at: ```text build/artifacts/den-qemu-aarch64.tar.zst ``` ### Extract The Bundle Choose a working directory and extract the bundle: ```bash mkdir -p /tmp/den-image tar -xf build/artifacts/den-qemu-aarch64.tar.zst -C /tmp/den-image cd /tmp/den-image/den-qemu-aarch64 ``` If your host `tar` cannot read `.tar.zst`, install `zstd` and select it explicitly: ```bash mkdir -p /tmp/den-image tar -I zstd -xf build/artifacts/den-qemu-aarch64.tar.zst -C /tmp/den-image cd /tmp/den-image/den-qemu-aarch64 ``` The extracted directory contains: ```text Image rootfs.cpio.gz den-rootfs.ext4 boot-qemu.sh manifest.toml SHA256SUMS ``` ### Inspect The Bundle Read the manifest: ```bash sed -n '1,120p' manifest.toml ``` The manifest records the target, architecture, Buildroot version, source commit, active generation, package count, and artifact hashes. Verify checksums on a Linux host: ```bash sha256sum -c SHA256SUMS ``` On macOS, install GNU coreutils if `sha256sum` is not available: ```bash brew install coreutils gsha256sum -c SHA256SUMS ``` ### Boot With Host QEMU If `qemu-system-aarch64` is installed on the host: ```bash ./boot-qemu.sh ``` Run the deterministic smoke path: ```bash ./boot-qemu.sh --smoke ``` Enable the developer autologin console: ```bash ./boot-qemu.sh --autologin ``` This adds `den.development=1 den.console=autologin` to the kernel command line. Use more memory: ```bash ./boot-qemu.sh --memory 4096 ``` Use a specific QEMU binary: ```bash ./boot-qemu.sh --qemu /path/to/qemu-system-aarch64 ``` On Apple Silicon with Homebrew QEMU: ```bash ./boot-qemu.sh --qemu /opt/homebrew/bin/qemu-system-aarch64 ``` Append extra kernel command-line text: ```bash ./boot-qemu.sh --append "systemd.log_level=debug" ``` ### Boot With The Builder Container If you do not have host QEMU installed, run the existing image through the optional builder container from inside the extracted bundle directory. Build the image from the repository root first if it is not already present: ```bash docker build -f docker/buildroot-builder.Dockerfile -t den-buildroot-builder:2026.02 . ``` ```bash docker run --rm -it \ -v "$PWD:/bundle" \ -w /bundle \ den-buildroot-builder:2026.02 \ ./boot-qemu.sh ``` For the smoke path: ```bash docker run --rm \ -v "$PWD:/bundle" \ -w /bundle \ den-buildroot-builder:2026.02 \ timeout 150 ./boot-qemu.sh --smoke ``` The smoke boot should print: ```text Den systemd: smoke complete ``` and then power off. ### Boot The Existing In-Repo Extracted Bundle If the bundle has already been built in this repo, the extracted copy may already exist at: ```text build/artifacts/den-qemu-aarch64 ``` Boot it without extracting again: ```bash cd build/artifacts/den-qemu-aarch64 ./boot-qemu.sh ``` Or through Docker with the optional builder image: ```bash docker run --rm -it \ -v "$PWD:/bundle" \ -w /bundle \ den-buildroot-builder:2026.02 \ ./boot-qemu.sh ``` ## Use The OCI Image If the local image has already been built, inspect it with: ```bash 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 the container: ```bash conda --version conda config --show channels default_channels channel_priority ``` The image includes `/etc/conda/.condarc` so conda uses `conda-forge` with strict channel priority and no Anaconda default channels by default. Run the deterministic OCI smoke: ```bash ct run oci-smoke ``` The smoke checks `/etc/os-release`, the current Den generation, and the conda-provided bash. This image is not booted with Den's kernel or initramfs. ## Use The UEFI Disk Image The UEFI disk artifacts are: ```text build/artifacts/den-uefi-aarch64.raw build/artifacts/den-uefi-aarch64.qcow2 ``` The raw disk boots in QEMU with AArch64 UEFI firmware: ```bash QEMU_BIN="$(brew --prefix qemu)/bin/qemu-system-aarch64" QEMU_EFI="$(brew --prefix qemu)/share/qemu/edk2-aarch64-code.fd" "$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 ``` To verify the UEFI path without typing the QEMU command: ```bash ct run uefi-image-smoke ``` ## Stop The Guest The `--smoke` path powers off automatically. For an interactive boot, use systemd's normal shutdown command from inside the guest when a shell is available: ```bash systemctl poweroff ``` If QEMU is running in a terminal and you need to leave the QEMU monitor, use QEMU's standard escape sequence: ```text Ctrl-a x ``` ## Current Limitations The existing artifacts are prototype QEMU AArch64 artifacts. They are not yet: - an installer, - a systemd-boot disk image, - a provider-ready cloud image, - a signed release artifact, - a redistributable image with complete SBOM, license, and provenance reports.