Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/zirconium-dev/zirconium/llms.txt

Use this file to discover all available pages before exploring further.

Zirconium uses Just as its build system orchestrator. The build system supports multiple output formats including ISO images, bootable disk images, and direct bootc installations.

​
Environment variables

The build system recognizes these environment variables:
​
IMAGE_FULL
string
default:"zirconium:latest"
The full container image name to build or use for image generation
​
BUILD_FILESYSTEM
string
default:"ext4"
Filesystem type for disk images. Common values: ext4, btrfs, xfs
​
BUILD_BASE_DIR
string
default:"."
Base directory for build outputs and temporary files
​
BUILD_FLAVOR
string
Build flavor variant. Set to nvidia to include NVIDIA driver support

​
Build commands

​
iso

Generates a bootable ISO image using bootc-image-builder. 
just iso [IMAGE]
Parameters:
  • IMAGE (optional): Container image to use. Defaults to $IMAGE_FULL or zirconium:latest
Process:
  1. Creates output/ directory for build artifacts
  2. Pulls the specified container image
  3. Runs bootc-image-builder with:
    • ISO output format
    • Btrfs root filesystem
    • librepo enabled for faster repository downloads
    • Configuration from iso.toml
  4. Outputs ISO to output/ directory
Requirements:
  • iso.toml configuration file in the working directory
  • Podman with root privileges
  • Sufficient disk space in /var/lib/containers/storage

​
rootful

Copies a container image from user context to root context for privileged operations. 
just rootful [IMAGE]
Parameters:
  • IMAGE (optional): Container image to copy. Defaults to $IMAGE_FULL or zirconium:latest
Use case: Required before running disk-image if the image was built in user context.

​
bootc

Executes bootc commands within a privileged container. 
just bootc [ARGS...]
Parameters:
  • ARGS: Arguments passed directly to the bootc command
Examples: 
just bootc install to-disk /dev/sda --wipe
Mounts:
  • /sys/fs/selinux - SELinux filesystem
  • /etc/containers - Container configuration
  • /var/lib/containers - Container storage
  • /dev - Device nodes
  • $BUILD_BASE_DIR (or .) mounted as /data

​
disk-image

Creates a bootable disk image file using bootc. 
just disk-image [FILESYSTEM]
Parameters:
  • FILESYSTEM (optional): Filesystem type. Defaults to $BUILD_FILESYSTEM or ext4
Process:
  1. Creates a 20GB sparse file at ${BUILD_BASE_DIR}/bootable.img if it doesn’t exist
  2. Installs the system to the image via loopback device
  3. Wipes any existing data on the image
Example with custom location: 
BUILD_BASE_DIR=/mnt/builds just disk-image btrfs

​
quick-iterate

Rapid development workflow that builds, transfers, and creates a disk image in one command. 
just quick-iterate
Process:
  1. Builds container image: podman build -t zirconium:latest .
  2. Copies image to root context: just rootful
  3. Creates disk image in /tmp: BUILD_BASE_DIR=/tmp just disk-image
Use case: Fast iteration during development. Uses /tmp to avoid cluttering the working directory.

​
Build stages

The Zirconium build process uses a multi-stage script system located in build_files/:

​
Naming convention

Scripts follow the pattern: NN-name-STAGE.sh where:
  • NN = execution order (00-99)
  • name = component name
  • STAGE = one of: pre, fetch, post

​
Stage types

Runs before package installation. Used for repository configuration and system preparation.Example: 00-base-pre.sh - System initialization
Installs packages via DNF. COPR repositories are enabled temporarily for specific packages.Examples:
  • 00-base-fetch.sh - Base system packages
  • 01-theme-fetch.sh - Desktop environment and theme packages
  • 02-nvidia-fetch.sh - NVIDIA drivers (when BUILD_FLAVOR=nvidia)
  • 99-misc-fetch.sh - Flatpak repository setup
Configures installed packages, copies system files, and enables services.Examples:
  • 00-base-post.sh - Copies system files, configures systemd
  • 01-theme-post.sh - Theme setup, font cache, service presets
  • 02-nvidia-post.sh - NVIDIA driver compilation and SELinux setup

​
Configuration files

​
iso.toml

Configuration for bootc-image-builder when generating ISO images. Should include:
  • Installation defaults
  • Kernel arguments
  • User setup
  • Network configuration

​
Containerfile/Dockerfile

The main container build file that orchestrates the build stages by executing scripts from build_files/ in sequence.

​
Build options

​
NVIDIA support

To build with NVIDIA driver support: 
BUILD_FLAVOR=nvidia podman build -t zirconium:nvidia .
This triggers 02-nvidia-fetch.sh and 02-nvidia-post.sh to install:
  • NVIDIA kernel modules via DKMS
  • CUDA libraries
  • nvidia-container-toolkit
  • Proprietary driver stack

​
Cache management

DNF cache is enabled during builds for faster rebuilds. The cache is automatically cleaned on build completion.

Build docs developers (and LLMs) love

Get started for freeTalk to us