'\" t
.\
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "DISTROBOX-ASSEMBLE" "1" "May 2024" "Distrobox" "User Manual"
.hy
.SH NAME
.IP
.nf
\f[C]
distrobox assemble
distrobox-assemble
\f[R]
.fi
.SH DESCRIPTION
.PP
distrobox-assemble takes care of creating or destroying containers in
batches, based on a manifest file.
The manifest file by default is \f[V]./distrobox.ini\f[R], but can be
specified using the \f[V]--file\f[R] flag.
.SH SYNOPSIS
.PP
\f[B]distrobox assemble\f[R]
.IP
.nf
\f[C]
--file:         path 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
\f[R]
.fi
.SH EXAMPLES
.PP
This is an example manifest file to create two containers:
.IP
.nf
\f[C]
[ubuntu]
additional_packages=\[dq]git vim tmux nodejs\[dq]
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=\[dq]git vim tmux nodejs\[dq]
home=/tmp/home
image=archlinux:latest
init=false
start_now=true
init_hooks=\[dq]touch /init-normal\[dq]
nvidia=true
pre_init_hooks=\[dq]touch /pre-init\[dq]
pull=true
root=false
replace=false
volume=\[dq]/tmp/test:/run/a /tmp/test:/run/b\[dq]
\f[R]
.fi
.PP
\f[B]Create\f[R]
.PP
We can bring them up simply using
.IP
.nf
\f[C]
distrobox assemble create
\f[R]
.fi
.PP
If the file is called \f[V]distrobox.ini\f[R] and is in the same
directory you\[cq]re launching the command, no further arguments are
needed.
You can specify a custom path for the file using
.IP
.nf
\f[C]
distrobox assemble create --file /my/custom/path.ini
\f[R]
.fi
.PP
\f[B]Replace\f[R]
.PP
By default, \f[V]distrobox assemble\f[R] will replace a container only
if \f[V]replace=true\f[R] is specified in the manifest file.
.PP
In the example of the manifest above, the ubuntu container will always
be replaced when running \f[V]distrobox assemble create\f[R], while the
arch container will not.
.PP
To force a replace for all containers in a manifest use the
\f[V]--replace\f[R] flag
.IP
.nf
\f[C]
distrobox assemble create --replace [--file my/custom/path.ini]
\f[R]
.fi
.PP
\f[B]Remove\f[R]
.PP
We can bring down all the containers in a manifest file by simply doing
.IP
.nf
\f[C]
distrobox assemble rm
\f[R]
.fi
.PP
Or using a custom path for the ini file
.IP
.nf
\f[C]
distrobox assemble rm --file my/custom/path.ini
\f[R]
.fi
.PP
\f[B]Test\f[R]
.PP
You can always test what distrobox \f[B]would do\f[R] by using the
\f[V]--dry-run\f[R] flag.
This command will only print what commands distrobox would do without
actually running them.
.PP
\f[B]Available options\f[R]
.PP
This is a list of available options with the corresponding type:
.PP
.TS
tab(@);
l l.
T{
Flag Name
T}@T{
Type
T}
_
T{
additional_flags
T}@T{
string
T}
T{
additional_packages
T}@T{
string
T}
T{
home
T}@T{
string
T}
T{
image
T}@T{
string
T}
T{
init_hooks
T}@T{
string
T}
T{
pre_init_hooks
T}@T{
string
T}
T{
volume
T}@T{
string
T}
T{
exported_apps
T}@T{
string
T}
T{
exported_bins
T}@T{
string
T}
T{
exported_bins_path
T}@T{
string
T}
T{
entry
T}@T{
bool
T}
T{
start_now
T}@T{
bool
T}
T{
init
T}@T{
bool
T}
T{
nvidia
T}@T{
bool
T}
T{
pull
T}@T{
bool
T}
T{
root
T}@T{
bool
T}
T{
unshare_ipc
T}@T{
bool
T}
T{
unshare_netns
T}@T{
bool
T}
T{
unshare_process
T}@T{
bool
T}
T{
unshare_devsys
T}@T{
bool
T}
T{
unshare_all
T}@T{
bool
T}
.TE
.PP
boolean options default to false if not specified.
string options can be broken in multiple declarations additively in
order to improve readability of the file:
.IP
.nf
\f[C]
[ubuntu]
image=ubuntu:latest
additional_packages=\[dq]git vim tmux nodejs\[dq]
additional_packages=\[dq]htop iftop iotop\[dq]
additional_packages=\[dq]zsh fish\[dq]
\f[R]
.fi
.PP
Be aware that if you\[cq]re doing lines with spaces, you need to quote
them.
If you\[cq]re doing multiple hooks (init or pre_init) in multiple lines,
end the line with a semicolon (;) in order to execute them one after the
other.
.PP
For an explanation of each of the option in the list, take a look at the
distrobox create usage, each option corresponds to one of the
\f[V]create\f[R] flags.
.PP
\f[B]Advanced example\f[R]
.IP
.nf
\f[C]
[tumbleweed_distrobox]
image=registry.opensuse.org/opensuse/distrobox
pull=true
additional_packages=\[dq]acpi bash-completion findutils iproute iputils sensors inotify-tools unzip\[dq]
additional_packages=\[dq]net-tools nmap openssl procps psmisc rsync man tig tmux tree vim htop xclip yt-dlp\[dq]
additional_packages=\[dq]git git-credential-libsecret\[dq]
additional_packages=\[dq]patterns-devel-base-devel_basis\[dq]
additional_packages=\[dq]ShellCheck ansible-lint clang clang-tools codespell ctags desktop-file-utils gcc golang jq python3\[dq]
additional_packages=\[dq]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\[dq]
additional_packages=\[dq]kubernetes-client helm\[dq]
init_hooks=GOPATH=\[dq]${HOME}/.local/share/system-go\[dq] GOBIN=/usr/local/bin go install github.com/golangci/golangci-lint/cmd/golangci-lint\[at]latest;
init_hooks=GOPATH=\[dq]${HOME}/.local/share/system-go\[dq] GOBIN=/usr/local/bin go install github.com/onsi/ginkgo/v2/ginkgo\[at]latest;
init_hooks=GOPATH=\[dq]${HOME}/.local/share/system-go\[dq] GOBIN=/usr/local/bin go install golang.org/x/tools/cmd/goimports\[at]latest;
init_hooks=GOPATH=\[dq]${HOME}/.local/share/system-go\[dq] GOBIN=/usr/local/bin go install golang.org/x/tools/gopls\[at]latest;
init_hooks=GOPATH=\[dq]${HOME}/.local/share/system-go\[dq] GOBIN=/usr/local/bin go install sigs.k8s.io/kind\[at]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=\[dq]htop\[dq]
exported_bins=\[dq]/usr/bin/htop /usr/bin/git\[dq]
exported_bins_path=\[dq]\[ti]/.local/bin\[dq]
\f[R]
.fi