NAME

       debos - Debian OS images builder

SYNOPSIS

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

       Application Options:

                -b, --fakemachine-backend=   Fakemachine backend to use (default: auto)
                    --artifactdir=           Directory for packed archives and ostree repositories (default: current directory)
                -t, --template-var=          Template variables (use -t VARIABLE:VALUE syntax)
                    --debug-shell            Fall into interactive shell on error
                -s, --shell=                 Redefine interactive shell binary (default: bash) (default: /bin/bash)
                    --scratchsize=           Size of disk backed scratch space
                -c, --cpus=                  Number of CPUs to use for build VM (default: 2)
                -m, --memory=                Amount of memory for 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 final recipe
                    --dry-run                Compose final recipe to build but without any real work started
                    --disable-fakemachine    Do not use fakemachine.

DESCRIPTION

       debos  is  a tool to make the creation of various Debian-based OS images simpler.  While most other tools
       focus on specific use-cases, debos is more meant as a tool-chain to make  common  actions  trivial  while
       providing enough rope to do whatever tweaking that might be required behind the scene.

       debos  expects  a  YAML  file  as  input and will run the actions listed in the file sequentially.  These
       actions should be self-contained and independent of each other.

       Some of the actions provided by debos to customize 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

       • 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

       • 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  can  be  found  at:  https://godoc.org/github.com/go-
       debos/debos/actions

INSTALLATION (DOCKER CONTAINER)

       Official debos container is available:

              docker pull godebos/debos

       See docker/README.md (https://github.com/go-debos/debos/blob/master/docker/README.md) for usage.

INSTALLATION (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 suites your needs
              go get -u github.com/go-debos/debos/cmd/debos
              /opt/src/gocode/bin/debos --help

SIMPLE EXAMPLE

       The  following  example  will  create  a  arm64  image,  install  several packages in it, change the file
       /etc/hostname to “debian” and finally make a tarball.

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

              architecture: arm64

              actions:
                - action: debootstrap
                  suite: "buster"
                  components:
                    - main
                    - non-free
                  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” if you would like to modify this name, you  can  provided  a
       different name for the variable image like this:

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

OTHER EXAMPLES

       This example builds a customized image for a Raspberry Pi 3.  https://github.com/go-debos/debos-recipes

ENVIRONMENT VARIABLES

       debos  read  a  predefined  list of environment variables from the host and propagates it to fakemachine.
       The set of environment variables is defined by environ_vars on cmd/debos/debos.go.  Currently the list of
       environment variables includes the proxy environment variables as 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.

       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 enviroment variable, or in other words, to prevent an environment variable to  be  propagated
       to fakemachine, use the same syntax without a value.  debos accept 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.  Prefer using an address that is valid on your network.
         debos will warn if 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 running debos with the --disable-fakemachine argument) creates and spawns a virtual machine
       using fakemachine (https://github.com/go-debos/fakemachine) and  executes  the  actions  defined  by  the
       recipe  inside  the  virtual  machine.   This  helps  ensure  recipes are reproducible no matter the host
       environment.

       Fakemachine can use different virtualisation backends to spawn the virtualmachine, for  more  information
       see the documentation under the fakemachine repository (https://github.com/go-debos/fakemachine).

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

                                                                                                        debos(1)