debos(1)

📦

version 1.1.7 · 6 versions

1.1.7 · ubuntu stonking (latest)
1.0.0+git20201203.e939090 · ubuntu jammy
1.1.1 · debian bookworm
1.1.3 · ubuntu noble
1.1.7 · ubuntu resolute
1.1.5 · debian trixie, ubuntu questing

🎀 debos(1) 🎀

okay bestie, welcome to the debos manual page — it's debos(1), and it's the one where we learn how to build Debian OS images. sit down, grab a strawberry matcha, we're doing this 💅

✨ NAME ✨

debos — Debian OS images builder 🦋

✨ SYNOPSIS ✨

debos [options] <recipe file in YAML>
debos [--help]

Application Options:

-b, --fakemachine-backend= — the Fakemachine backend to use (default: auto)
--artifactdir= — the directory for packed archives and ostree repositories (default: current directory)
-t, --template-var= — template variables (use -t VARIABLE:VALUE syntax)
--debug-shell — fall into an interactive shell on error
-s, --shell= — redefine the interactive shell binary (default: bash) (default: /bin/bash)
--scratchsize= — size of disk backed scratch space
-c, --cpus= — number of CPUs to use for the build VM (default: 2)
-m, --memory= — amount of memory for the build VM (default: 2048MB)
--show-boot — show boot/console messages from the fake machine
-e, --environ-var= — environment variables (use -e VARIABLE:VALUE syntax)
-v, --verbose — verbose output
--print-recipe — print the final recipe
--dry-run — compose the final recipe to build but without any real work started
--disable-fakemachine — do not use fakemachine.

✨ DESCRIPTION ✨

debos is the tool that makes creating all sorts of Debian-based OS images so much simpler. like, most other tools out there hyperfixate on one specific use-case 😭 but debos is designed as a toolchain — it makes the common actions basically trivial while still handing you enough rope to do whatever behind-the-scenes tweaking you might need. main character energy tbh 👑

debos expects a YAML file as input. a general overview of a YAML recipe and of the templating engine it uses lives in the debos recipe syntax documentation 📓

debos runs the actions listed in the recipe file sequentially, one after another. and the way that these actions should be self-contained and independent of each other?? iconic. no cap.

some of the actions debos provides to customise and produce images are:

apt: install packages and their dependencies with apt
debootstrap: construct the target rootfs with debootstrap
download: download a single file from the internet
filesystem-deploy: deploy a root filesystem to an image previously created
image-partition: create an image file, make partitions and format them
install-deb: install packages and their dependencies from local deb packages
ostree-commit: create an OSTree commit from rootfs
ostree-deploy: deploy an OSTree branch to the image
overlay: do a recursive copy of directories or files to the target filesystem
pack: create a tarball with the target filesystem
pacman: install packages and their dependencies with pacman
pacstrap: construct the target rootfs with pacstrap
raw: directly write a file to the output image at a given offset
recipe: includes the recipe actions at the given path
run: allows to run a command or script in the filesystem or in the host
unpack: unpack files from archive in the filesystem

a full syntax description of all the debos actions lives in the debos actions documentation 💖

✨ GET IN TOUCH! ✨

💬 join us on Matrix at #debos:matrix.debian.social to chat about usage or development of debos.
🪲 to report a bug, issue or feature request, create a new GitHub Issue.
❓ please use the GitHub Discussion forum to ask questions about how to use Debos or to discuss best ways of creating recipes.

like, the community is right there, come say hi 🫶

✨ INSTALLATION (DOCKER CONTAINER) ✨

there's an official debos container available 🎀

docker pull godebos/debos

see docker/README.md for usage.

✨ USING DEBOS IN GITHUB ACTIONS ✨

debos can be run in GitHub Actions using the official container with KVM support for isolated and reproducible builds 🔥 the --fakemachine-backend=kvm option is specified to ensure KVM is used as expected:

jobs:
  build:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/go-debos/debos:main
      options: --device=/dev/kvm
    steps:
      - uses: actions/checkout@v4
      - run: debos --fakemachine-backend=kvm --print-recipe recipe.yaml

✨ INSTALLATION FROM SOURCE (UNDER DEBIAN) ✨

sudo apt install golang git libglib2.0-dev libostree-dev qemu-system-x86 \
     qemu-user-static debootstrap systemd-container

export GOPATH=/opt/src/gocode # or whatever suits your needs

go install -v github.com/go-debos/debos/cmd/debos@latest

/opt/src/gocode/bin/debos --help

✨ SIMPLE EXAMPLE ✨

the following example will create an arm64 image, install several packages in it, change the file /etc/hostname to debian and finally make a tarball of the complete system 🌸

{{- $image := or .image "debian.tgz" -}}

architecture: arm64

actions:
  - action: debootstrap
    suite: trixie
    components:
      - main
      - non-free-firmware
    mirror: https://deb.debian.org/debian
    variant: minbase

  - action: apt
    packages:
      - sudo
      - openssh-server
      - adduser
      - systemd-sysv
      - firmware-linux

  - action: run
    chroot: true
    command: echo debian > /etc/hostname

  - action: pack
    file: {{ $image }}
    compression: gz

to run it, create a file named example.yaml and run:

debos example.yaml

the final tarball will be named debian.tgz. and if you would like to modify the fileame, you can provide a different name for the variable image like this:

debos -t image:"debian-arm64.tgz" example.yaml

✨ OTHER EXAMPLE RECIPES ✨

see the bundled example recipes for some more detailed example recipes. additional more detailed example recipes are stored under debos-recipes 🍓

✨ ENVIRONMENT VARIABLES ✨

debos reads a predefined list of environment variables from the host and propagates them to the fakemachine build environment. the set of environment variables is defined by environ_vars in cmd/debos/debos.go. currently the list of environment variables includes the proxy environment variables documented at:

https://wiki.archlinux.org/index.php/proxy_settings

the list of environment variables currently exported to fakemachine is:

http_proxy, https_proxy, ftp_proxy, rsync_proxy, all_proxy, no_proxy

while the elements of environ_vars are in lower case, for each element both lower and upper case variants are probed on the host and, if found, propagated to fakemachine ✨ so if the host has the environment variables HTTP_PROXY and no_proxy defined, both will be propagated to fakemachine respecting the case. iykyk.

the command line options --environ-var and -e can be used to specify, overwrite and unset environment variables for fakemachine with the syntax:

debos -e ENVIRONVAR:VALUE ...

to unset an environment variable — or in other words, to prevent an environment variable being propagated to fakemachine — use the same syntax without a value. debos accepts multiple -e simultaneously 💅

✨ PROXY CONFIGURATION ✨

while the proxy related environment variables are exported from the host to fakemachine, there are two known sources of issues 😭:

using localhost will not work from fakemachine. use an address which is valid on your network. debos will warn if the environment variables contain localhost.
in case you are running applications and/or scripts inside fakemachine you may need to check which are the proxy environment variables they use. different apps are known to use different environment variable names and different case for environment variable names.

✨ FAKEMACHINE BACKEND ✨

debos (unless you're running debos with the --disable-fakemachine argument) creates and spawns a virtual machine using fakemachine and executes the actions defined by the recipe inside the virtual machine 🧚 this helps ensure recipes are reproducible no matter the host environment. obsessed.

Fakemachine can use different virtualisation backends to spawn the virtual machine — for more information see the fakemachine documentation.

by default the backend will automatically be selected based on what is supported by the host machine, but this can be overridden using the --fakemachine-backend / -b option. and if no backends are supported, debos reverts to running the recipe on the host without creating a fakemachine.

performance of the backends is roughly as follows: kvm is faster than uml is faster than qemu. using --disable-fakemachine is slightly faster than kvm, but requires root permissions ⚠️

benchmark times for running pine-a64-plus/debian.yaml on an Intel Pentium G4560T with SSD:

backend --disable-fakemachine — Wall Time: 8 min — Prerequisites: root permissions
backend -b kvm — Wall Time: 9 min — Prerequisites: access to /dev/kvm
backend -b uml — Wall Time: 18 min — Prerequisites: package user-mode-linux installed
backend -b qemu — Wall Time: 166 min — Prerequisites: none

and that's the whole page, bestie 💖 go forth and build images, you're gonna slay.

okay so that's it from the debos(1) manual — this whole thing is the debos(1) page, General Commands Manual vibes, and you've officially read it top to bottom 🎀 consider the vibe check passed. mwah 💅✨🦋

📦 where this page comes from

ubuntu stonking: debos 1.1.7-1ubuntu1 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-02: a language model's rewrite of the original, under its terms