Update docs for v3.3 and modern linux distributions

docs/requirements.in

@@ -5,5 +5,6 @@ flask-babel
 plantweb
 sphinx
 sphinx-issues
+sphinx-reredirects
 sphinx-rtd-theme
 sphinxcontrib-mermaid

docs/requirements.txt

@@ -66,10 +66,13 @@ sphinx==5.3.0
     # via
     #   -r docs/requirements.in
     #   sphinx-issues
+    #   sphinx-reredirects
     #   sphinx-rtd-theme
     #   sphinxcontrib-jquery
 sphinx-issues==4.0.0
     # via -r docs/requirements.in
+sphinx-reredirects==0.1.3
+    # via -r docs/requirements.in
 sphinx-rtd-theme==2.0.0
     # via -r docs/requirements.in
 sphinxcontrib-applehelp==1.0.8

docs/source/conf.py

@@ -49,7 +49,8 @@ def _get_version():
               'sphinxcontrib.jquery',
               'sphinxcontrib.mermaid',
               'exec_directive',
-              'indico_uml_directive']
+              'indico_uml_directive',
+              'sphinx_reredirects']
 
 # sphinx-issues config
 issues_github_path = 'indico/indico'
@@ -246,3 +247,12 @@ def _get_version():
 
 mermaid_version = '10.2.3'
 mermaid_verbose = True
+
+redirects = {
+    'installation/production/centos': '../rpm',
+    'installation/production/debian': '../deb',
+    'installation/production/centos/apache': '../../rpm/apache',
+    'installation/production/centos/nginx': '../../rpm/nginx',
+    'installation/production/debian/apache': '../../deb/apache',
+    'installation/production/debian/nginx': '../../deb/nginx',
+}

docs/source/config/auth.rst

@@ -440,8 +440,8 @@ The ``shibboleth`` authentication/identity providers are available by
 default, but due to how the protocol works you need to use the Apache
 webserver to use SAML atuhentication provider.
 
-You can find guides on how to set it up for :ref:`CentOS <centos-apache-shib>`
-and :ref:`Debian <deb-apache-shib>`.
+You can find guides on how to set it up for :ref:`Alma/Rocky Linux <rpm-apache-shib>`
+and :ref:`Debian/Ubuntu <deb-apache-shib>`.
 
 If you also have an LDAP server, it may be a good idea to use the
 ``shibboleth`` authentication provider and connect it to an ``ldap``

docs/source/installation/development.rst

@@ -13,24 +13,24 @@ requires NodeJS to be present. You can find information on how to install NodeJS
 Do not use the default NodeJS packages from your Linux distribution as they are usually outdated or come with
 an outdated npm version.
 
-Since only few Linux distributions include Python 3.9 in their package managers, we recommend installing
-`pyenv <https://github.com/pyenv/pyenv-installer>`_ and then install the latest Python 3.9 version using
-``pyenv install 3.9.9`` (adapt this command in case a newer version is available).
+Since only the latest Linux distributions include Python 3.12 in their package managers, we recommend installing
+`pyenv <https://github.com/pyenv/pyenv-installer>`_ and then install the latest Python 3.12 version using
+``pyenv install 3.12``.
 
 .. tip::
 
     You can run ``pyenv doctor`` once you installed and enabled pyenv in order to see whether all dependencies are
     met. There's a good chance that you need to install some additional system packages beyond those listed below, and using
     this tool will tell you what exactly you need.
 
-CentOS/Fedora
-+++++++++++++
+RPM-based distributions (Alma, Rocky, Fedora)
++++++++++++++++++++++++++++++++++++++++++++++
 
 .. code-block:: shell
 
-    yum install -y gcc redis libjpeg-turbo-devel libxslt-devel libxml2-devel \
+    dnf install -y gcc redis libjpeg-turbo-devel libxslt-devel libxml2-devel \
         libffi-devel pcre-devel libyaml-devel redhat-rpm-config \
-        postgresql postgresql-server postgresql-contrib libpq-devel
+        postgresql postgresql-server postgresql-contrib libpq-devel pango
     systemctl start redis.service postgresql.service
 
 
@@ -40,7 +40,7 @@ Debian/Ubuntu
 .. code-block:: shell
 
     apt install -y --install-recommends libxslt1-dev libxml2-dev libffi-dev libpcre3-dev \
-        libyaml-dev build-essential redis-server postgresql libpq-dev
+        libyaml-dev build-essential redis-server postgresql libpq-dev libpango1.0-dev
 
 Then on Debian::
 
@@ -56,7 +56,7 @@ macOS
 
 We recommend that you use `Homebrew <https://brew.sh/>`_::
 
-    brew install redis libjpeg libffi pcre libyaml postgresql
+    brew install redis libjpeg libffi pcre libyaml postgresql pango
     brew services start postgresql
     brew services start redis
 
@@ -74,14 +74,13 @@ developers keep all their code inside a ``dev`` or ``code`` dir. We will assume
 We will need a virtualenv where to run Indico::
 
     cd ~/dev/indico
-    pyenv local 3.9.9
+    pyenv local 3.12
     python -m venv env
 
 .. note::
 
     After setting the version with pyenv, it's a good idea to use ``python -V`` to ensure you are really running that
-    particular Python version; depending on the shell you may need to restart your shell first. In case you installed
-    a newer version than 3.9.9 earlier, adapt the pyenv command accordingly.
+    particular Python version; depending on the shell you may need to restart your shell first.
 
 
 .. _cloning:
@@ -216,7 +215,7 @@ static files as well.
 
 You should obviously install nginx first::
 
-    sudo yum install nginx  # centos/fedora
+    sudo dnf install nginx  # alma/rocky/fedora
     sudo apt install nginx  # debian/ubuntu
     brew install nginx      # macOS
 

docs/source/installation/latex.rst

@@ -8,17 +8,29 @@ as the *Book of Abstracts* and the PDF versions of contributions.  If
 you do not need these features, you can skip this part of the documentation
 and avoid installing LaTeX altogether.
 
-Since Indico requires quite a few LaTeX packages which are not always]
+Since Indico requires quite a few LaTeX packages which are not always
 installed by default when using the texlive packages of the various
 linux distributions, we recommend installing it manually.
 
+.. note::
+
+    If you know what you're doing, feel free to try using your distribution's "full"
+    texlive package (often named ``texlive-full``, ``texlive-scheme-full``, or similar)
+    instead of using the texlive installer.
+
+    However, e.g. on Alma9 there are some LaTeX packages missing which Indico needs.
+    A possible workaround for this (which works fine) is using the packages from
+    Fedora 34, but this is not straightforward at all.
+
 First of all, you will need to install some dependencies so that all TeX
 formats are generated successfully upon TeXLive installation.
 
 .. code-block:: shell
 
-    yum install fontconfig ghostscript     # CentOS / CC7
-    apt install libfontconfig1 ghostscript # Debian / Ubuntu
+    # If you use Alma or Rocky:
+    dnf install perl ghostscript fontconfig wget
+    # If you use Debian or Ubuntu:
+    apt install perl ghostscript libfontconfig1
 
 You are now ready to install TeXLive. The following commands should work
 fine to install everything you need.

docs/source/installation/production/_intro.rst

@@ -1,5 +1,5 @@
-We provide guides to install Indico on CentOS and Debian systems.
-While other distributions are not officially supported, they should
+We provide guides to install Indico on Alma/Rocky Linux and Debian/Ubuntu
+systems. While other distributions are not officially supported, they should
 work fine, but the installation steps (especially package names) may
 need some slight adjustments.
 

docs/source/installation/production/_old_distros.rst

@@ -0,0 +1,6 @@
+.. warning::
+    Older distributions are unsupported. We do not test with them, and things
+    may or may not be broken. We do not recommend such distributions unless
+    you have a very strong technical reason for it and also the necessary system
+    administration knowledge to know how to debug and deal with any compatibility
+    issues you may encounter.

docs/source/installation/production/deb/_intro.rst

@@ -0,0 +1,4 @@
+These guides have been verified to work on **Debian 12** (Bookworm), **Ubuntu 22.04 LTS**
+(Jammy Jellyfish) and **Ubuntu 24.04 LTS** (Noble Numbat).
+
+.. include:: ../_old_distros.rst

docs/source/installation/production/debian/apache.rst → docs/source/installation/production/deb/apache.rst

@@ -4,15 +4,15 @@ Apache
 1. Install Packages
 -------------------
 
-PostgreSQL is installed from its upstream repos to get a much more recent version.
+PostgreSQL is installed from its upstream repos to get a more recent version.
 
 .. code-block:: shell
 
     apt install -y lsb-release wget curl gnupg
-    echo "deb http://apt.postgresql.org/pub/repos/apt/ $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list
-    wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | apt-key add -
+    wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | gpg --dearmor > /usr/share/keyrings/pgdg-archive-keyring.gpg
+    echo "deb [signed-by=/usr/share/keyrings/pgdg-archive-keyring.gpg] https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list
     apt update
-    apt install -y --install-recommends postgresql-13 libpq-dev apache2 libapache2-mod-proxy-uwsgi libapache2-mod-xsendfile libxslt1-dev libxml2-dev libffi-dev libpcre3-dev libyaml-dev libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev libncurses5-dev libncursesw5-dev xz-utils liblzma-dev uuid-dev build-essential redis-server
+    apt install -y --install-recommends postgresql-16 libpq-dev apache2 libapache2-mod-proxy-uwsgi libapache2-mod-xsendfile libxslt1-dev libxml2-dev libffi-dev libpcre3-dev libyaml-dev libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev libncurses5-dev libncursesw5-dev xz-utils liblzma-dev uuid-dev build-essential redis-server git libpango1.0-dev
 
 
 If you use Debian, run this command:
@@ -26,7 +26,7 @@ If you use Ubuntu, run this instead:
 
 .. code-block:: shell
 
-    apt install -y libjpeg-turbo8-dev zlib1g-dev
+    apt install -y libjpeg-turbo8-dev
 
 Afterwards, make sure the services you just installed are running:
 
@@ -47,7 +47,7 @@ extensions (which can only be done by the Postgres superuser).
     su - postgres -c 'createdb -O indico indico'
     su - postgres -c 'psql indico -c "CREATE EXTENSION unaccent; CREATE EXTENSION pg_trgm;"'
 
-.. warning::
+.. important::
 
     Do not forget to setup a cronjob that creates regular database
     backups once you start using Indico in production!
@@ -69,7 +69,9 @@ most cases.
 
     processes = 4
     enable-threads = true
-    socket = 127.0.0.1:8008
+    chmod-socket = 770
+    chown-socket = indico:www-data
+    socket = /opt/indico/web/uwsgi.sock
     stats = /opt/indico/web/uwsgi-stats.sock
     protocol = uwsgi
 
@@ -169,7 +171,7 @@ We also need a systemd unit to start uWSGI.
         Alias /robots.txt /opt/indico/web/static/robots.txt
 
         SetEnv UWSGI_SCHEME https
-        ProxyPass / uwsgi://127.0.0.1:8008/
+        ProxyPass / unix:/opt/indico/web/uwsgi.sock|uwsgi://localhost/
 
         <Directory /opt/indico>
             AllowOverride None
@@ -282,15 +284,12 @@ Python features.
 
     source ~/.bashrc
 
-You are now ready to install Python 3.9:
-
-Run ``pyenv install --list | egrep '^\s*3\.9\.'`` to check for the latest available version and
-then install it and set it as the active Python version (replace ``x`` in both lines).
+You are now ready to install Python 3.12:
 
 .. code-block:: shell
 
-    pyenv install 3.9.x
-    pyenv global 3.9.x
+    pyenv install 3.12
+    pyenv global 3.12
 
 This may take a while since pyenv needs to compile the specified Python version. Once done, you
 may want to use ``python -V`` to confirm that you are indeed using the version you just installed.
@@ -302,7 +301,7 @@ You are now ready to install Indico:
     python -m venv --upgrade-deps --prompt indico ~/.venv
     source ~/.venv/bin/activate
     echo 'source ~/.venv/bin/activate' >> ~/.bashrc
-    pip install wheel
+    pip install setuptools wheel
     pip install uwsgi
     pip install indico
 
@@ -359,32 +358,16 @@ server is rebooted:
 9. Optional: Get a Certificate from Let's Encrypt
 -------------------------------------------------
 
-.. note::
-
-    You need to use at least Debian 9 (Stretch) to use certbot.
-    If you are still using Debian 8 (Jessie), consider updating
-    or install certbot from backports.
-
-
-If you use Ubuntu, install the certbot PPA:
-
-.. code-block:: shell
-
-    apt install -y software-properties-common
-    add-apt-repository -y ppa:certbot/certbot
-    apt update
-
-
 To avoid ugly TLS warnings in your browsers, the easiest option is to
 get a free certificate from Let's Encrypt. We also enable the cronjob
 to renew it automatically:
 
 
 .. code-block:: shell
 
-    apt install -y python-certbot-apache
-    certbot --apache --rsa-key-size 4096 --no-redirect --staple-ocsp -d YOURHOSTNAME
-    rm -rf /etc/ssl/indico
+    apt install -y certbot python3-certbot-apache
+    certbot --apache --no-redirect --staple-ocsp -d YOURHOSTNAME
+    rm -f /etc/ssl/indico/indico.*
     systemctl start certbot.timer
     systemctl enable certbot.timer
 
@@ -416,8 +399,8 @@ it in Indico:
 
 .. code-block:: shell
 
-    apt install -y libapache2-mod-shib2
-    a2enmod shib2
+    apt install -y libapache2-mod-shib
+    a2enmod shib
 
 2. Configure Shibboleth
 ^^^^^^^^^^^^^^^^^^^^^^^