DISTROBOX-ASSEMBLE(1)

NAME

    distrobox assemble
    distrobox-assemble

DESCRIPTION

distrobox-assemble takes care of creating or destroying containers in batches, based on a manifest file. The manifest file by default is ./distrobox.ini, but can be specified using the --file flag.

SYNOPSIS

distrobox assemble

    --file:         path or URL to the distrobox manifest/ini file
    --name/-n:      run against a single entry in the manifest/ini file
    --replace/-R:       replace already existing distroboxes with matching names
    --dry-run/-d:       only print the container manager command generated
    --verbose/-v:       show more verbosity
    --version/-V:       show version

EXAMPLES

This is an example manifest file to create two containers:

    [ubuntu]
    additional_packages="git vim tmux nodejs"
    image=ubuntu:latest
    init=false
    nvidia=false
    pull=true
    root=false
    replace=true
    start_now=false
    # You can add comments using this #
    [arch] # also inline comments are supported
    additional_packages="git vim tmux nodejs"
    home=/tmp/home
    image=archlinux:latest
    init=false
    start_now=true
    init_hooks="touch /init-normal"
    nvidia=true
    pre_init_hooks="touch /pre-init"
    pull=true
    root=false
    replace=false
    volume="/tmp/test:/run/a /tmp/test:/run/b"

Create

We can bring them up simply using

    distrobox assemble create

If the file is called distrobox.ini and is in the same directory you’re launching the command, no further arguments are needed. You can specify a custom path for the file using

    distrobox assemble create --file /my/custom/path.ini

Or even specify a remote file, by using an URL:

    distrobox-assemble create --file https://raw.githubusercontent.com/89luca89/dotfiles/master/distrobox.ini

Replace

By default, distrobox assemble will replace a container only if replace=true is specified in the manifest file.

In the example of the manifest above, the ubuntu container will always be replaced when running distrobox assemble create, while the arch container will not.

To force a replace for all containers in a manifest use the --replace flag

    distrobox assemble create --replace [--file my/custom/path.ini]

Remove

We can bring down all the containers in a manifest file by simply doing

    distrobox assemble rm

Or using a custom path for the ini file

    distrobox assemble rm --file my/custom/path.ini

Test

You can always test what distrobox would do by using the --dry-run flag. This command will only print what commands distrobox would do without actually running them.

Available options

This is a list of available options with the corresponding type:

Types legend:

•   bool: true or false

•   string: a single string, for example home="/home/luca-linux/dbox"

•   string_list: multiple strings, for example additional_packages="htop vim git". Note that string_list can be declared multiple times to be compounded:

        [ubuntu]
        image=ubuntu:latest
        additional_packages="git vim tmux nodejs"
        additional_packages="htop iftop iotop"
        additional_packages="zsh fish"

Flag Name | Type |
additional_flags | string_list | Additional flags to pass to the container manager
additional_packages | string_list | Additional packages to install inside the container
home | string | Which home directory should the container use
image | string | Which image should the container use, look here for a list
init_hooks | string_list | Commands to run inside the container, after the packages setup
pre_init_hooks | string_list | Commands to run inside the container, before the packages setup
volume | string_list | Additional volumes to mount inside the containers
exported_apps | string_list | App names or desktopfile paths to export
exported_bins | string_list | Binaries to export
exported_bins_path | string | Optional path where to export binaries (default: $HOME/.local/bin)
entry | bool | Generate an entry for the container in the app list (default: false)
start_now | bool | Start the container immediately (default: false)
init | bool | Specify if this is an initful container (default: false)
nvidia | bool | Specify if you want to enable NVidia drivers integration (default: false)
pull | bool | Specify if you want to pull the image every time (default: false)
root | bool | Specify if the container is rootful (default: false)
unshare_ipc | bool | Specify if the container should unshare the ipc namespace (default: false)
unshare_netns | bool | Specify if the container should unshare the network namespace (default: false)
unshare_process | bool | Specify if the container should unshare the process (pid) namespace (default: false)
unshare_devsys | bool | Specify if the container should unshare /dev (default: false)
unshare_all | bool | Specify if the container should unshare all the previous options (default: false)

For further explanation of each of the option in the list, take a look at the distrobox create usage, each option corresponds to one of the create flags.

Advanced example

    [tumbleweed_distrobox]
    image=registry.opensuse.org/opensuse/distrobox
    pull=true
    additional_packages="acpi bash-completion findutils iproute iputils sensors inotify-tools unzip"
    additional_packages="net-tools nmap openssl procps psmisc rsync man tig tmux tree vim htop xclip yt-dlp"
    additional_packages="git git-credential-libsecret"
    additional_packages="patterns-devel-base-devel_basis"
    additional_packages="ShellCheck ansible-lint clang clang-tools codespell ctags desktop-file-utils gcc golang jq python3"
    additional_packages="python3-bashate python3-flake8 python3-mypy python3-pipx python3-pycodestyle python3-pyflakes python3-pylint python3-python-lsp-server python3-rstcheck python3-yapf python3-yamllint rustup shfmt"
    additional_packages="kubernetes-client helm"
    init_hooks=GOPATH="${HOME}/.local/share/system-go" GOBIN=/usr/local/bin go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest;
    init_hooks=GOPATH="${HOME}/.local/share/system-go" GOBIN=/usr/local/bin go install github.com/onsi/ginkgo/v2/ginkgo@latest;
    init_hooks=GOPATH="${HOME}/.local/share/system-go" GOBIN=/usr/local/bin go install golang.org/x/tools/cmd/goimports@latest;
    init_hooks=GOPATH="${HOME}/.local/share/system-go" GOBIN=/usr/local/bin go install golang.org/x/tools/gopls@latest;
    init_hooks=GOPATH="${HOME}/.local/share/system-go" GOBIN=/usr/local/bin go install sigs.k8s.io/kind@latest;
    init_hooks=ln -sf /usr/bin/distrobox-host-exec /usr/local/bin/conmon;
    init_hooks=ln -sf /usr/bin/distrobox-host-exec /usr/local/bin/crun;
    init_hooks=ln -sf /usr/bin/distrobox-host-exec /usr/local/bin/docker;
    init_hooks=ln -sf /usr/bin/distrobox-host-exec /usr/local/bin/docker-compose;
    init_hooks=ln -sf /usr/bin/distrobox-host-exec /usr/local/bin/flatpak;
    init_hooks=ln -sf /usr/bin/distrobox-host-exec /usr/local/bin/podman;
    init_hooks=ln -sf /usr/bin/distrobox-host-exec /usr/local/bin/xdg-open;
    exported_apps="htop"
    exported_bins="/usr/bin/htop /usr/bin/git"
    exported_bins_path="~/.local/bin"