Podman Build Guide

Complete guide to building Redox OS using Podman containers

Overview

The Podman build method is the recommended approach for building Redox OS. It provides a consistent, reproducible build environment by using containerization, eliminating issues caused by different host configurations.

Why Podman? Podman provides rootless containers with better security than traditional Docker, and it’s the default containerization solution for Redox OS builds.

Prerequisites

System Requirements

• Operating System: Linux, macOS, FreeBSD, or Windows WSL2
• Memory: At least 8GB RAM (16GB recommended)
• Disk Space: 20-30GB free space
• Podman: Version 3.0 or higher

Required Software

Linux (Debian/Ubuntu)

sudo apt-get update
sudo apt-get install podman curl git make pkg-config \
  fuse3 libfuse3-dev fuse-overlayfs slirp4netns gdb-multiarch

Linux (Fedora)

sudo dnf install podman curl git make fuse3 fuse3-devel \
  fuse-overlayfs slirp4netns gdb

Linux (Arch)

sudo pacman -S podman curl git make fuse3 fuse-overlayfs \
  slirp4netns gdb

macOS (Homebrew)

brew install podman git make curl

FreeBSD

sudo pkg install podman git gmake curl gdb

Bootstrap Installation

Redox provides an automated bootstrap script that installs all dependencies and sets up the build environment.

Using the Bootstrap Script

1. Download the Bootstrap Script

   curl -sf https://gitlab.redox-os.org/redox-os/redox/raw/master/podman_bootstrap.sh -o podman_bootstrap.sh
   
2. Make it Executable

   chmod +x podman_bootstrap.sh
   
3. Run the Bootstrap

   For QEMU (recommended):

   ./podman_bootstrap.sh -e qemu
   

   For VirtualBox:

   ./podman_bootstrap.sh -e virtualbox
   

What the Bootstrap Does

The podman_bootstrap.sh script performs these actions:

Dependency Installation

• Detects your operating system
• Installs Podman and required packages
• Installs the selected emulator (QEMU or VirtualBox)
• Sets up FUSE and overlay filesystem support

Rust Installation

• Checks for existing Rust installations
• Offers to install rustup if not present
• Configures the stable Rust toolchain
• Updates PATH for cargo binaries

Repository Clone

• Clones the Redox OS repository from GitLab
• Creates .config with PODMAN_BUILD=1
• Sets up the directory structure

Manual Setup

If you prefer to set up manually or the bootstrap script doesn’t work for your system:

1. Clone the Repository

git clone https://gitlab.redox-os.org/redox-os/redox.git --origin upstream
cd redox

2. Create Configuration File

Create a .config file in the repository root:

.config

PODMAN_BUILD?=1

Optional configuration for ARM64 Macs:

.config

PODMAN_BUILD?=1
ARCH=aarch64

Add REPO_BINARY=1 to use pre-built packages for much faster builds (recommended for first-time users)

3. Install Rust

If you don’t have Rust installed:

curl https://sh.rustup.rs -sSf | sh -s -- --default-toolchain stable -y
source $HOME/.cargo/env

Building Redox OS

Container Setup

The first time you run make, the build system will automatically create the Podman container:

make all

This process:

1. Builds a Podman image based on podman/redox-base-containerfile
2. Installs build dependencies inside the container
3. Sets up the Rust toolchain in the container
4. Creates a tag file at build/container.tag

The initial container build can take 10-30 minutes depending on your internet connection and CPU speed.

Build Process Flow

When using Podman builds, make targets automatically delegate to the container:

Configuration Variables

The Podman build system uses several environment variables defined in mk/podman.mk:

IMAGE_TAG · string · default: "redox-base"

Docker image tag for the Podman container

CONTAINER_WORKDIR · string · default: "/mnt/redox"

Working directory inside the container

USE_SELINUX · integer · default: "1"

Enable SELinux volume flags (:Z) for systems with SELinux

PODMAN_CACHE_PULL · integer · default: "1"

Pull cached layers from Docker Hub to speed up builds

Build Examples

Standard Build

# Build default configuration (desktop x86_64)
make all

# Run in QEMU
make qemu

# Set configuration in .config
echo 'CONFIG_NAME=server' >> .config

# Build and run
make all
make qemu

# Configure for ARM64
echo 'ARCH=aarch64' >> .config

# Build
make all

# Use pre-built packages for faster builds
echo 'REPO_BINARY=1' >> .config
echo 'CONFIG_NAME=minimal' >> .config

make all

Container Management

Container Shell Access

To get a shell inside the build container:

make container_shell

This is useful for:

• Debugging build issues
• Inspecting build artifacts
• Running custom commands in the build environment

Rebuilding the Container

If you need to rebuild the container (e.g., after updating the Containerfile):

make container_clean
make all

container_clean will remove the container and all cached layers. The next build will take longer.

Container Cleanup

# Remove container tag and home directory
make container_clean

# Force remove container image
podman image rm --force redox-base

# Complete Podman system reset (removes all images and containers)
podman system reset

Podman Configuration Details

Volume Mounts

The container mounts these volumes:

# Source code (with SELinux label)
$(ROOT):/mnt/redox:Z

# Podman home directory (persists cargo cache, etc.)
$(PODMAN_HOME):/root:Z

Environment Variables

These variables are passed to the container:

# Build configuration
ARCH=$(ARCH)
BOARD=$(BOARD)
CONFIG_NAME=$(CONFIG_NAME)
FILESYSTEM_CONFIG=$(FILESYSTEM_CONFIG)
PREFIX_BINARY=$(PREFIX_BINARY)
REPO_BINARY=$(REPO_BINARY)
REPO_NONSTOP=$(REPO_NONSTOP)
REPO_OFFLINE=$(REPO_OFFLINE)

# Disable Podman inside container
PODMAN_BUILD=0

# CI and debugging
CI=$(CI)
COOKBOOK_LOGS=$(COOKBOOK_LOGS)
TESTBIN=$(TESTBIN)

Container Capabilities

The container runs with these capabilities:

--cap-add SYS_ADMIN    # Required for FUSE mounting
--device /dev/fuse     # FUSE device access
--network=host         # Host network access
--pids-limit=-1        # Unlimited PIDs

Filesystem Tools in Podman

By default, filesystem tools (redoxfs, redox_installer) run on the host. To run them inside Podman:

.config

FSTOOLS_IN_PODMAN=1

Running filesystem tools in Podman requires proper FUSE support in your container environment.

Troubleshooting

Container fails to build

Symptoms: Error during podman build command

Solutions:

• Check your internet connection
• Verify Podman is properly installed: podman --version
• Try cleaning and rebuilding: make container_clean && make all
• Check system logs: journalctl -xe | grep podman

FUSE permission errors

Symptoms: Cannot mount filesystem, permission denied

Solutions:

• Ensure FUSE is installed on host
• Check FUSE device permissions: ls -l /dev/fuse
• Verify user is in fuse group: groups
• Try rootless Podman: podman unshare cat /proc/self/uid_map

SELinux issues

Symptoms: Volume mount errors on Fedora/RHEL

Solutions:

• Disable SELinux volume flags in .config:
  USE_SELINUX=0
  
• Or configure SELinux to allow container access

Slow builds

Symptoms: Builds take hours to complete

Solutions:

• Enable binary packages:
  echo 'REPO_BINARY=1' >> .config
  
• Enable pre-built toolchain:
  echo 'PREFIX_BINARY=1' >> .config
  
• Use a minimal configuration:
  echo 'CONFIG_NAME=minimal' >> .config
  

Advanced Topics

Custom Containerfile

You can specify a custom Containerfile:

.config

CONTAINERFILE=podman/my-custom-containerfile

Cache Management

Podman builds support layer caching via Docker Hub:

.config

# Enable cache push (requires authentication)
PODMAN_CACHE_PUSH=1

# Disable cache pull
PODMAN_CACHE_PULL=0

Multi-Architecture Builds

Build for different architectures from the same host:

# Build for x86_64
make all ARCH=x86_64

# Build for aarch64
make all ARCH=aarch64

# Build for RISC-V
make all ARCH=riscv64gc

Next Steps

Configuration Options

Customize your build settings

Recipe System

Learn about building packages