Skip to main content

​
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

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

​
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:
  • Detects your operating system
  • Installs Podman and required packages
  • Installs the selected emulator (QEMU or VirtualBox)
  • Sets up FUSE and overlay filesystem support
  • Checks for existing Rust installations
  • Offers to install rustup if not present
  • Configures the stable Rust toolchain
  • Updates PATH for cargo binaries
  • 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

# Build default configuration (desktop x86_64)
make all

# Run in QEMU
make qemu

​
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

Symptoms: Error during podman build commandSolutions:
  • 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
Symptoms: Cannot mount filesystem, permission deniedSolutions:
  • 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
Symptoms: Volume mount errors on Fedora/RHELSolutions:
  • Disable SELinux volume flags in .config: 
    USE_SELINUX=0
  • Or configure SELinux to allow container access
Symptoms: Builds take hours to completeSolutions:
  • 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

Build docs developers (and LLMs) love

Get started for freeTalk to us