Install the latest documentation toolchain

Install the Documentation Toolchain

Table of Contents

• About this Page
• 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:

About this Page

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.

💡	For Contributors This method is intended solely for tooling development and maintenance! This stack can be used locally for building. However, we strongly recommend using the following container for regular contributions: Uyuni Docs Helper instead!

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