Upgrade ======= It is important to keep your Indico instance up to date to have the latest bug fixes and features. Upgrading can be done with almost no user-facing downtime. .. warning:: When upgrading a production system it is highly recommended to create a database backup before starting. .. important:: If you are upgrading from Indico v3.2.x or older to v3.3 or newer, make sure to fully read and understand the :ref:`Upgrading from 3.x to 3.3 ` guide before starting with any of the upgrade steps below. .. _upgrade-3-to-312: Upgrading to 3.3.12 ------------------- .. note:: This change is only applicable if you use LaTeX functionality in Indico, ie if you have :data:`XELATEX_PATH` set in your ``indico.conf`` file. If you use Alma/Rocky (or any other RPM-based distribution), the SELinux config changed and you need to run the SELinux setup step once again; see the relevant docs for an :ref:`nginx-based setup ` and an :ref:`Apache-based setup `. Then run ``restorecon -R /opt/indico/{cache,tmp}`` to apply the updated SELinux policy to the related directories. Afterwards, follow the :ref:`PDF generation guide ` to install Podman and configure Indico to use it. You can then remove the system-level TeXLive installation, either by deleting ``/opt/texlive`` or by using your package manager to uninstall it. Upgrading to 3.3.10 ------------------- .. note:: This change is only applicable when using nginx as your web server. Edit the ``/etc/nginx/conf.d/indico.conf`` file and replace this block: .. code-block:: nginx location /.xsf/indico/ { internal; alias /opt/indico/; } with this one (adding the ``add_header`` lines, everything else is unchanged): .. code-block:: nginx location /.xsf/indico/ { internal; alias /opt/indico/; add_header Content-Security-Policy $upstream_http_content_security_policy; add_header Content-Security-Policy-Report-Only $upstream_http_content_security_policy_report_only; add_header Reporting-Endpoints $upstream_http_reporting_endpoints; } Then restart nginx: .. code-block:: shell systemctl restart nginx.service .. _upgrade-3-to-3: Upgrading between 3.x versions ------------------------------ First of all, stop the Celery worker. To do so, run this as *root*: .. code-block:: shell systemctl stop indico-celery.service Now switch to the *indico* user and activate the virtualenv: .. code-block:: shell su - indico source ~/.venv/bin/activate If you use Alma/Rocky, update your PATH to avoid errors in case the new Indico version needs to install an updated version of the PostgreSQL client library (psycopg2). If you use a different Postgres version, you need to adapt the command accordingly: .. code-block:: shell export PATH="$PATH:/usr/pgsql-16/bin" .. _upgrade-3-to-3-indico: You are now ready to install the latest version of Indico: .. hint:: Are you upgrading from Indico v3.2.x or older to v3.3 or newer? Then you have to jump to the :ref:`Upgrading from 3.x to 3.3 ` guide now! .. code-block:: shell pip install -U indico .. _upgrade-3-to-3-plugins: If you installed the official plugins, update them too: .. code-block:: shell pip install -U indico-plugins It is a good idea to ensure you are using the latest recommended Python version: .. code-block:: shell indico setup upgrade-python Some versions may include database schema upgrades. Make sure to perform them immediately after upgrading. If there are no schema changes, the command will simply do nothing. .. code-block:: shell indico db upgrade indico db --all-plugins upgrade .. note:: Some database structure changes require an *exclusive lock* on some tables in the database. Unless you have very high activity on your instance, this lock can be acquired quickly, but if the upgrade command seems to hang for more than a few seconds, you can restart uWSGI by running ``systemctl restart indico-uwsgi.service`` as *root* (in a separate shell, i.e. don't abort the upgrade command!) which will ensure nothing is accessing Indico for a moment. When using LaTeX using the recommended containerized setup, it is also a good idea to fetch the latest container image so it doesn't need to be done on the fly while handling a request: .. code-block:: shell indico maint pull-latex-image Unless you just restarted uWSGI, it is now time to reload it so the new version is actually used: .. code-block:: shell touch ~/web/indico.wsgi Also start the Celery worker again (once again, as *root*): .. code-block:: shell systemctl start indico-celery.service .. _upgrade-3-to-33: Upgrading from 3.x to 3.3 ------------------------- When updating to Indico v3.3 you need to perform some extra steps since the required Python version has been raised from Python 3.9 to Python 3.12. .. attention:: If you are still using **CentOS 7** (or 8), you are required to **update your operating system** to version **9** - your system is not only too old, but also going end-of-life in the middle of 2024. Since CentOS no longer exists in its original form, we recommend using **AlmaLinux 9** or **Rocky Linux 9**. You can find guides on the internet on how to do such an upgrade in-place (we never tried this!), but it is almost certainly easier to just use a new VM and migrate your Indico installations to that one. If you are using an older **Debian** (Buster or Bullseye) or **Ubuntu** (Focal) release, switching to the latest one is also highly recommended - we no longer test on older releases, and things may be broken. Upgrading in-place is possible, but our same advice applies here: We never tried this and cannot help you with it; migrating to a new VM is almost certainly the easier and safer option. Please also read the :ref:`2.x to 3.x ` guide below which explains how to migrate your Indico data to a new system. The general :ref:`upgrade guide between 3.x versions ` above still applies, you just need to perform some additional steps. Anything below assumes you are on a supported Linux distribution (or know exactly what you're doing). Before the :ref:`Indico upgrade step ` (``pip install -U indico``), you need to install the required Python version: .. code-block:: shell indico setup upgrade-python --force-version 3.12 Confirm both the warning about the requested version not being within the spec (which is based on the previous Indico version) and the warning about having to re-install packages with :kbd:`Y`. Now you just need to install the *setuptools* package and then continue with installing the new Indico version and updating the symlink for the static assets: .. code-block:: shell pip install setuptools pip install -U indico indico setup create-symlinks ~/web/ You can now resume the regular upgrade guide :ref:`right after the ` ``pip install -U indico`` step. .. _upgrade-2-to-3: Upgrading from 2.x to 3.x ------------------------- The upgrade from 2.x to 3.x is a major change since Indico now requires Python 3. We also strongly recommend upgrading your database to PostgreSQL 16 or newer (PostgreSQL 13 is the minimum required version we still test with). .. note:: As of Indico 3.2, the upgrade **will fail** on Postgres 10 and older. .. warning:: If you are using any custom plugins they will most likely no longer work and need to be updated. Contact the developers of these plugins to see whether they already have a version compatible with Python 3 and Indico 3. Due to the significant changes in the environment, we recommend using a **freshly installed server/VM** with the latest long-term-supported version of your preferred Linux distribution. .. note:: In case you are using CentOS 7, please note that CentOS 7 is soon reaching its end-of-life date (mid 2024), and Indico v3.3 is no longer compatible with this very old distribution. Please use Alma/Rocky 9, or the latest Debian/Ubuntu LTS release instead. When following the :ref:`production installation guide `, there are a few places where you need to do something differently: - Instead of running ``indico db prepare``, restore a dump of your old Postgres database - You still need to run ``indico setup wizard`` to create some of the directories, but compare the generated config file with your old one and update any settings you may have changed manually (e.g. for LDAP or SSO authentication) - You need to perform the database structure upgrades just like during any other Indico upgrade: ``indico db upgrade`` and ``indico db --all-plugins upgrade`` - Copy the contents of the ``/opt/indico/archive`` folder from your old instance and ensure owner, group and permissions are correct. This step is critical as this folder contains all the files uploaded to Indico If you need any help with the upgrade or encounter any issues, please open a thread in `our forum`_. Upgrading from 2.x to 3.x in-place ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. warning:: If you are not experienced with Linux system administration, we highly recommend you to either ask someone from your IT department for assistance and/or follow our recommendation of using a new server/VM to install Indico v3. In case you prefer to perform the upgrade in place on your existing server, you will need to compare the installation guides of 2.3 and 3.x and apply the differences manually. This should be fairly easy for someone with Linux system administration experience, but here are some important points: - Create a backup of both your Postgres database and ``/opt/indico/archive`` - Stop, disable and and uninstall uWSGI and delete the old config file. To support the latest Python version uWSGI is now installed into the Indico virtual environment using ``pip`` - Delete the ``~/.venv`` folder of the Indico user and recreate it using the commands from the setup guide - Make sure to update your webserver config to use the more modern TLS defaults .. _our forum: https://talk.getindico.io/