{"id":13607021,"url":"https://github.com/go-debos/debos","last_synced_at":"2026-02-06T16:08:54.599Z","repository":{"id":24139897,"uuid":"99103619","full_name":"go-debos/debos","owner":"go-debos","description":"Debian OS builder","archived":false,"fork":false,"pushed_at":"2025-04-05T10:15:54.000Z","size":497,"stargazers_count":573,"open_issues_count":118,"forks_count":149,"subscribers_count":28,"default_branch":"main","last_synced_at":"2025-04-05T11:24:01.508Z","etag":null,"topics":["hacktoberfest"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/go-debos.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-08-02T10:23:22.000Z","updated_at":"2025-04-05T10:15:57.000Z","dependencies_parsed_at":"2023-02-16T17:31:43.935Z","dependency_job_id":"f5d3b833-e36a-422c-9652-89a54ac14fe3","html_url":"https://github.com/go-debos/debos","commit_stats":{"total_commits":417,"total_committers":50,"mean_commits":8.34,"dds":0.7961630695443644,"last_synced_commit":"227cf70102e8411c110bb16bb5ebf33db2af8409"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-debos%2Fdebos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-debos%2Fdebos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-debos%2Fdebos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-debos%2Fdebos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/go-debos","download_url":"https://codeload.github.com/go-debos/debos/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248560078,"owners_count":21124590,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest"],"created_at":"2024-08-01T19:01:14.823Z","updated_at":"2026-02-06T16:08:54.592Z","avatar_url":"https://github.com/go-debos.png","language":"Go","funding_links":[],"categories":["Go","Build systems"],"sub_categories":[],"readme":"# debos - Debian OS image builder\n\n## Synopsis\n\n```\ndebos [options] \u003crecipe file in YAML\u003e\ndebos [--help]\n```\n\nApplication Options:\n\n```\n  -b, --fakemachine-backend=   Fakemachine backend to use (default: auto)\n      --artifactdir=           Directory for packed archives and ostree repositories (default: current directory)\n  -t, --template-var=          Template variables (use -t VARIABLE:VALUE syntax)\n      --debug-shell            Fall into interactive shell on error\n  -s, --shell=                 Redefine interactive shell binary (default: bash) (default: /bin/bash)\n      --scratchsize=           Size of disk backed scratch space\n  -c, --cpus=                  Number of CPUs to use for build VM (default: 2)\n  -m, --memory=                Amount of memory for build VM (default: 2048MB)\n      --show-boot              Show boot/console messages from the fake machine\n  -e, --environ-var=           Environment variables (use -e VARIABLE:VALUE syntax)\n  -v, --verbose                Verbose output\n      --print-recipe           Print final recipe\n      --dry-run                Compose final recipe to build but without any real work started\n      --disable-fakemachine    Do not use fakemachine.\n```\n\n## Description\n\ndebos is a tool to make the creation of various Debian-based OS images\nsimpler. While most other tools focus on specific use-cases, debos is\ndesigned to be a toolchain making common actions trivial while providing\nenough rope to do whatever tweaking which might be required behind the\nscenes.\n\ndebos expects a YAML file as input. A general overview of a YAML recipe and of\nthe templating engine used can be found in the\n[debos recipe syntax documentation](https://pkg.go.dev/github.com/go-debos/debos/actions#hdr-Recipe_syntax).\n\ndebos runs the actions listed in the recipe file sequentially. These actions\nshould be self-contained and independent of each other.\n\nSome of the actions provided by debos to customise and produce images are:\n\n* `apt`: install packages and their dependencies with `apt`\n* `debootstrap`: construct the target rootfs with `debootstrap`\n* `download`: download a single file from the internet\n* `filesystem-deploy`: deploy a root filesystem to an image previously created\n* `image-partition`: create an image file, make partitions and format them\n* `install-deb`: install packages and their dependencies from local deb packages\n* `ostree-commit`: create an OSTree commit from rootfs\n* `ostree-deploy`: deploy an OSTree branch to the image\n* `overlay`: do a recursive copy of directories or files to the target filesystem\n* `pack`: create a tarball with the target filesystem\n* `pacman`: install packages and their dependencies with pacman\n* `pacstrap`: construct the target rootfs with pacstrap\n* `raw`: directly write a file to the output image at a given offset\n* `recipe`: includes the recipe actions at the given path\n* `run`: allows to run a command or script in the filesystem or in the host\n* `unpack`: unpack files from archive in the filesystem\n\nA full syntax description of all the debos actions can be found in the\n[debos actions documentation](https://godoc.org/github.com/go-debos/debos/actions).\n\n## Get in touch!\n\n💬 Join us on Matrix at [#debos:matrix.debian.social](https://matrix.to/#/#debos:matrix.debian.social)\nto chat about usage or development of debos.\n\n🪲 To report a bug, issue or feature request, create a new\n[GitHub Issue](https://github.com/go-debos/debos/issues).\n\n❓ Please use the [GitHub Discussion forum](https://github.com/go-debos/debos/discussions)\nto ask questions about how to use Debos or to discuss best ways of creating\nrecipes.\n\n## Installation (Docker container)\n\nAn official debos container is available:\n```\ndocker pull godebos/debos\n```\n\nSee [docker/README.md](docker/README.md) for usage.\n\n## Using debos in GitHub Actions\n\ndebos can be run in GitHub Actions using the official container with KVM support\nfor isolated and reproducible builds. The `--fakemachine-backend=kvm` option is\nspecified to ensure KVM is used as expected:\n\n```yaml\njobs:\n  build:\n    runs-on: ubuntu-latest\n    container:\n      image: ghcr.io/go-debos/debos:main\n      options: --device=/dev/kvm\n    steps: \n      - uses: actions/checkout@v4\n      - run: debos --fakemachine-backend=kvm --print-recipe recipe.yaml\n```\n\n## Installation from source (under Debian)\n\n```bash\nsudo apt install golang git libglib2.0-dev libostree-dev qemu-system-x86 \\\n     qemu-user-static debootstrap systemd-container\n\nexport GOPATH=/opt/src/gocode # or whatever suits your needs\n\ngo install -v github.com/go-debos/debos/cmd/debos@latest\n\n/opt/src/gocode/bin/debos --help\n```\n\n## Simple example\n\nThe following example will create an arm64 image, install several\npackages in it, change the file `/etc/hostname` to `debian` and finally\nmake a tarball of the complete system.\n\n```yaml\n{{- $image := or .image \"debian.tgz\" -}}\n\narchitecture: arm64\n\nactions:\n  - action: debootstrap\n    suite: trixie\n    components:\n      - main\n      - non-free-firmware\n    mirror: https://deb.debian.org/debian\n    variant: minbase\n\n  - action: apt\n    packages:\n      - sudo\n      - openssh-server\n      - adduser\n      - systemd-sysv\n      - firmware-linux\n\n  - action: run\n    chroot: true\n    command: echo debian \u003e /etc/hostname\n\n  - action: pack\n    file: {{ $image }}\n    compression: gz\n```\n\nTo run it, create a file named `example.yaml` and run:\n\n```bash\ndebos example.yaml\n```\n\nThe final tarball will be named `debian.tgz`. If you would like to modify\nthe fileame, you can provide a different name for the variable image\nlike this:\n\n```bash\ndebos -t image:\"debian-arm64.tgz\" example.yaml\n```\n\n## Other example recipes\n\nSee the [bundled example recipes](doc/examples) for some more detailed example\nrecipes. Additional more detailed example recipes are stored under [debos-recipes](https://github.com/go-debos/debos-recipes).\n\n## Environment variables\n\ndebos reads a predefined list of environment variables from the host and\npropagates them to the fakemachine build environment. The set of\nenvironment variables is defined by `environ_vars` in\n`cmd/debos/debos.go`. Currently the list of environment variables includes\nthe proxy environment variables documented at:\n\nhttps://wiki.archlinux.org/index.php/proxy_settings\n\nThe list of environment variables currently exported to fakemachine is:\n\n```\nhttp_proxy, https_proxy, ftp_proxy, rsync_proxy, all_proxy, no_proxy\n```\n\nWhile the elements of `environ_vars` are in lower case, for each element\nboth lower and upper case variants are probed on the host and if found\npropagated to fakemachine. So if the host has the environment variables\nHTTP_PROXY and no_proxy defined, both will be propagated to fakemachine\nrespecting the case.\n\nThe command line options `--environ-var` and `-e` can be used to specify,\noverwrite and unset environment variables for fakemachine with the syntax:\n\n```bash\ndebos -e ENVIRONVAR:VALUE ...\n```\n\nTo unset an environment variable, or in other words, to prevent an\nenvironment variable being propagated to fakemachine, use the same syntax\nwithout a value. debos accepts multiple -e simultaneously.\n\n## Proxy configuration\n\nWhile the proxy related environment variables are exported from the host\nto fakemachine, there are two known sources of issues:\n\n* Using localhost will not work from fakemachine. Use an address which\n  is valid on your network. debos will warn if the environment variables\n  contain localhost.\n\n* In case you are running applications and/or scripts inside fakemachine\n  you may need to check which are the proxy environment variables they\n  use. Different apps are known to use different environment variable\n  names and different case for environment variable names.\n\n## Fakemachine Backend\n\ndebos (unless running debos with the `--disable-fakemachine` argument)\ncreates and spawns a virtual machine using [fakemachine](https://github.com/go-debos/fakemachine)\nand executes the actions defined by the recipe inside the virtual machine.\nThis helps ensure recipes are reproducible no matter the host environment.\n\nFakemachine can use different virtualisation backends to spawn the virtual\nmachine, for more information see the [fakemachine documentation](https://github.com/go-debos/fakemachine).\n\nBy default the backend will automatically be selected based on what is\nsupported by the host machine, but this can be overridden using the\n`--fakemachine-backend` / `-b` option. If no backends are supported,\ndebos reverts to running the recipe on the host without creating a\nfakemachine.\n\nPerformance of the backends is roughly as follows: `kvm` is faster than\n`uml` is faster than `qemu`. Using `--disable-fakemachine` is slightly\nfaster than `kvm`, but requires root permissions.\n\nBenchmark times for running [pine-a64-plus/debian.yaml](https://github.com/go-debos/debos-recipes/blob/9a25b4be6c9136f4a27e542f39ab7e419fc852c9/pine-a64-plus/debian.yaml)\non an Intel Pentium G4560T with SSD:\n\n| Backend | Wall Time | Prerequisites |\n| --- | --- | --- |\n| `--disable-fakemachine` | 8 min | root permissions |\n| `-b kvm` | 9 min | access to `/dev/kvm` |\n| `-b uml` | 18 min | package `user-mode-linux` installed  |\n| `-b qemu` | 166 min | none |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgo-debos%2Fdebos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgo-debos%2Fdebos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgo-debos%2Fdebos/lists"}