Container setup
The current documentation toolchain lives in uyuni-project/uyuni-docs on master. Builds run inside the uyuni-docs-builder container. You only need Podman or Docker and Task on the host — not Go, Node.js, Ruby, or Antora.
Official source for this procedure: docs/container-setup.md in uyuni-docs.
The builder image is created on your machine with task container:build. There is no separate registry image to pull.
Download a host system
SUSE hosts for the zypper commands on this page:
| System | Download |
|---|---|
| openSUSE Leap 16.0 | get.opensuse.org/leap |
| openSUSE Tumbleweed | get.opensuse.org/tumbleweed |
| SUSE Linux Enterprise 16 | suse.com/download/sles |
Other widely used distributions. Ubuntu 26.04 LTS is covered in Ubuntu. The rest of this table is download pages only.
| Distribution | Download |
|---|---|
| Ubuntu | ubuntu.com/download |
| Debian | debian.org/download |
| Linux Mint | linuxmint.com/download.php |
| Fedora | fedoraproject.org/workstation/download |
| Arch Linux | archlinux.org/download |
| Manjaro | manjaro.org/download |
| Pop!_OS | system76.com/pop |
| Zorin OS | zorin.com/os/download |
| Rocky Linux | rockylinux.org/download |
| AlmaLinux | almalinux.org/get-almalinux |
1. Install Podman or Docker
openSUSE Leap 16.0 / SLES 16.0 / Tumbleweed:
sudo zypper install podman git curl
Ubuntu 26.04 LTS: see Ubuntu below. That section is the full path: requirements, the builder image, and a first docs build.
Verify:
podman --version
# or
docker --version
Ubuntu
Ubuntu 26.04 LTS can host the same container workflow. Download the image from ubuntu.com/download/server (or the desktop image if this is a workstation).
Install requirements
Git clones the docs. Curl runs the Task install script. Podman or Docker runs the builder.
sudo apt-get update
sudo apt-get install -y git curl podman
Docker is fine instead of Podman:
sudo apt-get install -y git curl docker.io
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
Log out and back in after joining the docker group.
podman --version
# or
docker --version
git --version
Build the container and work with the docs
git clone https://github.com/uyuni-project/uyuni-docs.git
cd uyuni-docs
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
task --version
task container:build
task container:build builds uyuni-docs-builder from Dockerfile.bci. Do this once, and again after that file changes. Then build the docs, for example the English Uyuni site:
task container:publish:uyuni LANGUAGES=en
HTML lands in build/en/ on the host. The full target list is in Build targets below. Do not install Task with apt if the packaged version is older than the script above.
2. Clone the repository
git clone https://github.com/uyuni-project/uyuni-docs.git
cd uyuni-docs
3. Install Task
Task drives the container. Use the upstream install script — do not install Task via zypper on Leap 16 or SLES 16; the packaged version is 2.x and is too old.
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin
Put ~/.local/bin on your $PATH:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
Verify:
task --version
4. Build the container image
This builds uyuni-docs-builder locally from Dockerfile.bci. It takes a few minutes and only needs to be done once, or after Dockerfile.bci changes.
task container:build
The image includes Go, Task, Antora, Asciidoctor-PDF, and zip.
5. Build targets
Run task with no arguments to list targets. Every build target has a container: equivalent. The local repository is mounted at /docs inside the container; output lands in build/ on the host.
Full publish (HTML + PDFs + zips)
task container:publish:dsc # MLM — documentation.suse.com
task container:publish:uyuni # Uyuni — website
task container:publish:webui-mlm # MLM WebUI
task container:publish:webui-uyuni # Uyuni WebUI
Before a product release, update config.yml. Then see Publish to documentation.suse.com or Publish Uyuni.
PDF builds
task container:pdf:mlm # All MLM PDFs — all books, all languages
task container:pdf:uyuni # All Uyuni PDFs — all books, all languages
task container:pdf:all # All PDFs
Limit languages
Each task builds all four languages by default. LANGUAGES= selects fewer:
task container:pdf:mlm LANGUAGES=en
task container:publish:uyuni LANGUAGES="en ja"
Allowed values: en, ja, zh_CN, ko. An empty or incorrect value stops the build. export LANGUAGES=en sets a default; a LANGUAGES= on the command line wins.
Control concurrency
PDF books run one job per core. JOBS= caps that:
task container:pdf:mlm LANGUAGES=en JOBS=4
Decrease JOBS= if a build runs out of memory.
Build one PDF book
There is no container:pdf task for a single book. Use container:run with the pdf task:
task container:run -- pdf BOOK=administration PRODUCT=mlm LANGUAGES=en
task container:run -- pdf BOOK=installation-and-upgrade PRODUCT=uyuni LANGUAGES=ja
Available books: installation-and-upgrade, client-configuration, administration, reference, retail, common-workflows, specialized-guides, legal.
Output is written to build/{lang}/pdf/.
OBS packages
task container:obs:mlm
task container:obs:uyuni
Validation
task container:validate:mlm
task container:validate:uyuni
Interactive shell
task container:shell
6. Find your build output
build/{lang}/ HTML output per language
build/pdf/{lang}/ Collected PDFs per language
build/packages/ OBS source tarballs
Troubleshooting
Error: short-name "uyuni-docs-builder:latest" did not resolve
You have not built the image yet. Run task container:build first.
Permission denied on build/ files (SELinux / rootless Podman)
The volume mount uses the :Z flag for SELinux relabelling. If errors persist, the working directory may be on a filesystem that blocks relabelling (for example NFS).
ERRO[0000] ... crun: ... permission denied
You may need rootless Podman user namespaces:
sudo sysctl -w kernel.unprivileged_userns_clone=1 # temporary
# or permanently:
echo 'kernel.unprivileged_userns_clone=1' | sudo tee /etc/sysctl.d/99-userns.conf
Docker vs Podman
CONTAINER_CMD in Taskfile.yml prefers podman, then docker. The :Z flag is harmless on Docker.
Rebuild after a Dockerfile.bci change
task container:build
Optional: local toolchain (no container)
If you need to run the tools on the host instead of in a container, see Local toolchain setup.
On Windows, set up WSL2 first: WSL2 setup guide.