OSBuild Debian Forge

A fork of osbuild, but for debian. Try to be as close as 1:1 os possible

Supports Debian 13+ (Trixie and newer)

Build-Pipelines for Operating System Artifacts

OSBuild is a pipeline-based build system for operating system artifacts. It defines a universal pipeline description and a build system to execute them, producing artifacts like operating system images, working towards an image build pipeline that is more comprehensible, reproducible, and extendable.

See the osbuild(1) man-page for details on how to run osbuild, the definition of the pipeline description, and more.

Project

• Website: https://www.osbuild.org
• Bug Tracker: https://github.com/osbuild/osbuild/issues
• Discussions: https://github.com/orgs/osbuild/discussions
• Matrix: #image-builder on fedoraproject.org
• Changelog: https://github.com/osbuild/osbuild/releases

Principles

1. OSBuild stages are never broken, only deprecated. The same manifest should always produce the same output.
2. OSBuild stages should be explicit whenever possible instead of e.g. relying on the state of the tree.
3. Pipelines are independent, so the tree is expected to be empty at the beginning of each.
4. Manifests are expected to be machine-generated, so OSBuild has no convenience functions to support manually created manifests.
5. The build environment is confined against accidental misuse, but this should not be considered a security boundary.
6. OSBuild may only use Python language features supported by the oldest target distribution.

Contributing

Please refer to the developer guide to learn about our workflow, code style and more.

Requirements

The requirements for this project are:

• bubblewrap >= 0.4.0
• python >= 3.6

Additionally, the built-in stages require:

• bash >= 5.0
• coreutils >= 8.31
• curl >= 7.68
• qemu-img >= 4.2.0
• debootstrap >= 1.0.0
• mmdebstrap >= 1.0.0
• tar >= 1.32
• util-linux >= 235
• skopeo
• ostree >= 2023.1

At build-time, the following software is required:

• python-docutils >= 0.13
• pkg-config >= 0.29

Testing requires additional software:

• pytest

Debian Support

Debian Forge supports Debian 13+ (Trixie and newer):

• trixie (Debian 13) - STABLE - Recommended for production
• forky (Debian 14) - TESTING - For development and testing
• sid (Debian Unstable) - UNSTABLE - Use with caution

Older releases are not supported:

• bookworm (Debian 12) - OLDSTABLE - Limited compatibility
• bullseye (Debian 11) - OLDOLDSTABLE - Not supported

Dynamic Runner System

Debian Forge automatically detects your distribution and uses the appropriate runner, just like Fedora OSBuild:

# OSBuild automatically detects and uses the right runner
$ ls -la runners/
org.osbuild.debian13*    # Debian 13 (Trixie) runner
org.osbuild.debian14*    # Debian 14 (Forky) runner  
org.osbuild.ubuntu2504*  # Ubuntu 25.04 (Plucky Puffin) runner
org.osbuild.ubuntu2404*  # Ubuntu 24.04 (Noble Numbat) runner
org.osbuild.debian-based* # Generic Debian-based runner
org.osbuild.linux*       # Generic Linux runner

Automatic Setup

# Setup the appropriate runner for your system
$ ./tools/debian-runner-setup

# List available runners
$ ./tools/debian-runner-setup list

Supported Distributions

• Debian: Trixie (13), Forky (14), Sid (unstable)
• Ubuntu: 24.04 LTS, 25.04 LTS, and future releases
• Other: Linux Mint, Pop!_OS, Elementary OS, Zorin OS, Kali Linux, Parrot OS

Running locally

The main binary is safe to run on your development machine with:

python3 -m osbuild --libdir .

To build an image:

python3 -m osbuild --libdir . ./test/test-debian-manifest.json

Every osbuild run uses a cache for downloaded files (sources) and, optionally, checkpoints of artifacts built by stages and pipelines. By default, this is kept in .osbuild (in the current working directory). The location of this directory can be specified using the --cache option.

For more information about the options and arguments, read man pages.

Build

Osbuild is a python script so it is not compiled. To verify changes made to the code use included makefile rules:

• make lint to run linter on top of the code
• make test-all to run base set of tests
• sudo make test-run to run extended set of tests (takes long time)

Also keep in mind that some tests require those prerequisites, otherwise they are skipped

sudo apt install -y debootstrap mmdebstrap sbuild schroot ostree qemu-utils

Installation

Installing osbuild requires to not only install the osbuild module, but also additional artifacts such as tools (i.e: osbuild-mpp) sources, stages, schemas and SELinux policies.

For this reason, doing an installation from source is not trivial and the easier way to install it is to create the set of RPMs that contain all these components.

This can be done with the rpm make target, i.e:

sudo dnf builddep osbuild.spec
make rpm

A set of RPMs will be created in the ./rpmbuild/RPMS/noarch/ directory and can be installed in the system using the distribution package manager, i.e:

sudo dnf install ./rpmbuild/RPMS/noarch/*.rpm

Repository

• web: https://github.com/osbuild/osbuild
• https: https://github.com/osbuild/osbuild.git
• ssh: git@github.com:osbuild/osbuild.git

License

• Apache-2.0
• See LICENSE file for details.