Updating Zammad

Note

🙈 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!

🤓 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.43.04.05.0latest stable (5.1)

Step 1: Ensure dependencies

Before proceeding, double-check that your system environment matches Zammad’s requirements.

Step 2: Stop Zammad
$ systemctl stop zammad
Step 3: Backup Zammad

See Backup and Restore for more information.

Step 4: Clear Zammad cache
$ zammad run rails r "Rails.cache.clear"
Step 5: Update Zammad
$ apt update
$ apt upgrade

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.

Step 7: Log into Zammad

Yes, that’s it!

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:

$ 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:

$ 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