Skip to main content

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.

1. Install Podman or Docker​

openSUSE Leap 16.0 / SLES 16.0 / Tumbleweed:

sudo zypper install podman

Ubuntu 26.04 LTS:

sudo apt-get install -y podman

Or install Docker instead:

sudo apt-get install -y docker.io
sudo systemctl enable --now docker
sudo usermod -aG docker $USER   # log out and back in after this

Verify:

podman --version
# or
docker --version

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 Multi-Linux Manager and 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.