Skip to content

Install the latest documentation toolchain

Jump to bottom
jcayouette edited this page Mar 5, 2025 · 32 revisions

Install the Documentation Toolchain

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.

💡

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:

Container: Uyuni Docs Helper

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 [email protected]: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

Install Po4a translation tools

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

    sudo zypper install -n po4a

Install 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

Add Supported locales to System

Add Locales

sudo locale-gen ja_JP.UTF-8 zh_CN.UTF-8 ko_KR.UTF-8
sudo update-locale
locale -a | grep -E "ja_JP|zh_CN|ko_KR"

Image Optimization Libraries

Install image optimization libraries:

sudo zypper install -n GraphicsMagick GraphicsMagick-devel

Install Required python 3 libraries:

  1. Install jinja2 and pyyaml:

    sudo zypper install -n python3-Jinja2 python3-PyYAML

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 [email protected]: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

Image Support Libraries

Install image support libraries:

sudo apt install graphicsmagick graphicsmagick-libmagick-dev-compat

Install Po4a translation tools

  1. Install po4a:

    sudo apt install po4a

Install Po4a Perl libraries

This tools are required for build localized versions of documentation.

  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

Add Supported locales to System

Add Locales

sudo locale-gen ja_JP.UTF-8 zh_CN.UTF-8 ko_KR.UTF-8
sudo update-locale
locale -a | grep -E "ja_JP|zh_CN|ko_KR"

Install Required python 3 libraries:

  1. Install jinja2 and pyyaml:

    sudo apt install python3-jinja2 python3-yaml

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/[email protected] @antora/[email protected]

  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 support library:

    gem install prawn-gmagick -v 0.0.9
uyuni logo

Uyuni Docs

Clone this wiki locally