From f2cd460914ca5c3d407cac350d232f07570ed734 Mon Sep 17 00:00:00 2001 From: ralf401 Date: Mon, 1 Jul 2024 14:56:03 +0200 Subject: [PATCH] Fixes #492 - Reworked 'Updating Zammad' section --- install/update.rst | 143 ++++++++++++++----------------------- prerequisites/software.rst | 1 + 2 files changed, 54 insertions(+), 90 deletions(-) diff --git a/install/update.rst b/install/update.rst index e8accae9..8d06f67f 100644 --- a/install/update.rst +++ b/install/update.rst @@ -1,29 +1,17 @@ Updating Zammad -*************** +=============== -.. note:: +Before updating Zammad, we strongly recommend to take a look at our +`release notes`_. You can find information about features and fixes as well as +technical remarks and breaking changes. - 🙈 Better safe than sorry - Before updating to a new version, please have a look into the - `release notes`_. These will provide further information on new - feature and fixes, but also technical remarks that may be relevant - during an upgrade! +Be aware that you **should not** skip major Zammad versions while updating. +That means, for example, your upgrade path from version 2.4 to 5.1 (assuming +this is the current stable) would be: +``2.4`` → ``3.0`` → ``4.0`` → ``5.0`` → ``latest stable (5.1)`` - 🤓 What about Zammad upgrade paths...? - In general we do not encourage you to skip Zammad versions or have - long update cycles. Zammad potentially stores very sensitive information - (personal information) which is why updating is very important. - - If you don't have time for updating all the time - (nobody got time for that, right?), please consider using `Zammad hosting`_ - for your and your customers' safety. - - In case you couldn't update for a longer time, please ensure to at least - update from **major to major** version. Big version jumps *may* work but - usually go terribly wrong. As example, expecting the current stable - version of Zammad being 5.1 and your instance being on Zammad 2.4, your - path would look like so: - ``2.4`` → ``3.0`` → ``4.0`` → ``5.0`` → ``latest stable (5.1)`` +If you don't have time for updating all the time, please consider +using `Zammad hosting`_ for your and your customers' safety. .. _release notes: https://zammad.com/en/releases .. _Zammad hosting: https://zammad.com/en/pricing @@ -34,7 +22,7 @@ Updating Zammad Step 1: Ensure dependencies Before proceeding, double-check that your system environment matches - :doc:`Zammad’s requirements `. + :doc:`Zammad's requirements `. Step 2: Stop Zammad .. code-block:: sh @@ -72,36 +60,40 @@ Updating Zammad $ zypper ref $ zypper up - .. warning:: - The package comes with maintenance scripts that will run regular - tasks during updates for you. - - | **However** - | Do not run Zammad updates unattended and **always** have a look - on the outputs these helper scripts generate. Ignoring said - output may lead to incomplete updates that may corrupt data or - lead to issues you find *way too late*. - - Step 6: Run required extra steps - Extra steps needed for updates are mentioned in our release news. - - `Updating Elasticsearch`_ may be relevant in this step. + tasks during updates for you. However, you should **always** have + a look on the outputs these helper scripts generate. Ignoring said + output may lead to incomplete updates that may corrupt data or + lead to issues. + + Step 6: Additional steps + Check release notes + If not already done, check our `release notes`_ if extra steps are + necessary and perform them, if applicable. + + Updating Elasticsearch + Updating Elasticsearch may be relevant, too. Make sure to have a + supported version of Elasticsearch installed (see + :ref:`software prerequisites ` for + supported versions). + + If you have to update Elasticsearch, please have a look at their + `documentation `_ + and follow the instructions. + + In case your are using plugins for Elasticsearch, make sure they are + updated as well (note: starting with Elasticsearch 8, the + ingest-attachment is no longer a plugin, it's now included in + Elasticsearch). Step 7: Log into Zammad Yes, that's it! .. tab:: Source - .. danger:: - - Zammad's former ``scheduler.rb`` script has changed and is now called - ``background-worker.rb``. Please ensure to reinstall the service - see - :ref:`source-install-systemd-reference`! - Step 1: Ensure dependencies Before proceeding, double-check that your system environment matches - :doc:`Zammad’s requirements `. + :doc:`Zammad's requirements `. .. tip:: **🤓 Ruby version changed?** @@ -162,10 +154,25 @@ Updating Zammad $ rails r "Locale.sync" $ rails r "Translation.sync" - Step 8: Start Zammad services + Step 8: Check if Elasticseach update is necessary + Make sure to have a + supported version of Elasticsearch installed (see + :ref:`software prerequisites ` for + supported versions). + + If you have to update Elasticsearch, please have a look at their + `documentation `_ + and follow the instructions. + + In case you are using plugins for Elasticsearch, make sure they are + updated as well (note: starting with Elasticsearch 8, the + ingest-attachment is no longer a plugin, it's now included in + Elasticsearch). + + Step 9: Start Zammad services Start the application server, web socket server and scheduler. - Step 9: Log into Zammad + Step 10: Log into Zammad Yes, that's it! .. tab:: Docker @@ -191,47 +198,3 @@ Updating Zammad $ docker-compose pull $ docker-compose up -d -Updating Elasticsearch -====================== - -.. warning:: - - Updating Elasticsearch **does not** automatically update it's plugins! - This usually isn't an issue if Zammad is being updated right after - Elasticsearch. - -If you want to upgrade your elasticsearch installation, please take a look at the -`elasticsearch documentation `_ -as it will have the most current information for you. - -If, for whatever reason, you need to rebuild your search index after upgrading, -use: - -.. code-block:: sh - - $ zammad run rake zammad:searchindex:rebuild - -Optionally, you can specify a number of CPU cores which are used for rebuilding -the searchindex, as in the following example with 8 cores: - -.. code-block:: sh - - $ zammad run rake zammad:searchindex:rebuild[8] - -.. hint:: **🤓 Zammad 5.2 comes with changes** - - As of Zammad 5.2 the reindex command has changed! - You will still be able to use the old method until Zammad 6, however, will - receive a deprecation warning. - -.. warning:: - - This step may fail if Zammad is under heavy load: Elasticsearch locks the - indices from deletion if you're pumping in new data, like receiving a new - ticket. (This only applies to single-node deployments, not clusters.) - - If it does, try killing Zammad first:: - - $ systemctl stop zammad - $ zammad run rake zammad:searchindex:rebuild - $ systemctl start zammad diff --git a/prerequisites/software.rst b/prerequisites/software.rst index d5635466..c0922ddb 100644 --- a/prerequisites/software.rst +++ b/prerequisites/software.rst @@ -226,6 +226,7 @@ The installation and configuration is out of our scope. Please follow the official vendor guides and ensure to have a tight security on your installation. +.. _prerequisites_elasticsearch: 2.8. Elasticsearch (optional) -----------------------------