Install the latest documentation toolchain

Install the Documentation Toolchain

Table of Contents

• OpenSUSE Leap 15.6
  • Install Git and Clone Repository
  • Install Build Dependencies
  • Install Ruby Dependencies
• Ubuntu 24.04
  • Install Git and Clone Repository
  • Install Build Dependencies
  • Install Ruby Dependencies
• Install NVM and Node
• Install Antora 3.1 and Lunrjs extension
• Install Asciidoctor
• Install Asciidoctor-pdf
• Install Po4a translation tools
• Install required po4a perl libraries
• Install Required python 3 libraries:

ℹ️	This method is intended solely for tooling development and maintenance! While you can set up this stack locally for building, we strongly recommend using the following container for regular contributions: uyuni-docs-helper instead!

This installation covers installation of the latest 2025 of the local devel tool-chain on a fresh OpenSUSE Leap 15.6 or Ubuntu 24.04 system with no additional packages installed.

OpenSUSE Leap 15.6

Install Git and Clone Repository

On a fresh system:

1. Install Git:

   sudo zypper in git

2. Clone the doc repo:

   git clone git@github.com:uyuni-project/uyuni-docs.git

Install Build Dependencies

1. Install the Required patterns:

   sudo zypper in -t pattern devel_C_C++ devel_python3 devel_perl

   ℹ️	You can search for available patterns with: sudo zypper search -t pattern

Install Ruby Dependencies

1. Install required libraries:

   sudo zypper install libyaml-devel sqlite3-devel readline-devel libopenssl-devel

2. Install rbenv the ruby version manager:

   git clone https://github.com/rbenv/rbenv.git ~/.rbenv

3. Add rbenv to path:

   echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc

4. Add init to bashrc:

   echo 'eval "$(rbenv init -)"' >> ~/.bashrc

5. Update terminal with latest bashrc:

   source ~/.bashrc

6. Install rbenv ruby-build tools:

   git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build

7. List ruby versions:

   > rbenv install -l
   ...
   2.7.7
   3.0.5
   3.1.3
   3.2.0
   ...

8. Install Ruby:

   rbenv install 3.0.0

   ℹ️

   Ruby 3.0.0 build depends on libopenssl 1.0.0 and libopenssl-devel 1.0.0. If Ruby 3.0.0 installation fails, install libopenssl-devel 1.0.0 with yast or zypper. In case of a package conflict, remove a later devel package temporarily. After Ruby installation you can re-install any other devel version again.

9. Set global version of ruby:

   rbenv global 3.0.0

Ubuntu 24.04

Install Git and Clone Repository

1. Install Git:

   sudo apt update
   sudo apt install git
   git --version

2. Clone the doc repo:

   git clone git@github.com:uyuni-project/uyuni-docs.git

Install Build Dependencies

Install Build Essentials:

sudo apt update
sudo apt install -y build-essential python3-dev libperl-dev libssl-dev

Install Ruby Dependencies

1. Install required libraries:

   sudo apt update
   sudo apt install -y libyaml-dev libsqlite3-dev libreadline-dev

2. Install rbenv the ruby version manager:

   git clone https://github.com/rbenv/rbenv.git ~/.rbenv

3. Add rbenv to path:

   echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc

4. Add init to bashrc:

   echo 'eval "$(rbenv init -)"' >> ~/.bashrc

5. Update terminal with latest bashrc:

   source ~/.bashrc

6. Install rbenv ruby-build tools:

   git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build

7. List ruby versions:

   > rbenv install -l
   ...
   2.7.7
   3.0.5
   3.1.3
   3.2.0
   ...

8. Install Ruby:

   rbenv install 3.0.0

9. Set global version of ruby:

   rbenv global 3.0.0

Install NVM and Node

1. Install NVM

   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash

2. Update terminal:

   source ~/.bashrc

3. Install LTS version of node:

   nvm install --lts

4. Use the latest version of node (prevents conflicts with older versions of antora):

   nvm use --lts

Install Antora 3.1 and Lunrjs extension

1. Install antora 3.1:

   npm i -g @antora/cli@3.1 @antora/site-generator@3.1

2. Install Lunrjs extension:

   npm i -g @antora/lunr-extension

Install Asciidoctor

1. Install Ruby Asciidoctor:

   gem install asciidoctor -v 2.0.17

2. Install Asciidoctor tabs

   npm i -g @asciidoctor/tabs

Install Asciidoctor-pdf

1. Install asciidoctor-pdf:

   gem install asciidoctor-pdf -v 1.6.2

2. Install pdf support packages:

   gem install rouge coderay rb-pygments concurrent-ruby asciidoctor-diagram

3. Install image optimization libraries:

   sudo zypper install -n GraphicsMagick GraphicsMagick-devel

4. Install support library:

   gem install prawn-gmagick -v 0.0.9

Install Po4a translation tools

1. Install po4a (Requires >= 0.62 or you will encounter build failures):

   sudo zypper install -n po4a

Install required po4a perl libraries

1. Install perl libraries. Run each of the following commands one at a time:

   sudo cpan install Locale::gettext
   sudo cpan install Text::WrapI18N
   sudo cpan install Term::ReadKey
   sudo cpan install Unicode::GCString

Install Required python 3 libraries:

1. Install jinja2 and pyyaml:

   sudo zypper install -n python3-Jinja2 python3-PyYAML