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 mayor to mayor 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)
- 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
$ yum update zammad
$ zypper ref $ zypper up
Warning
The package comes with maintenance scripts that will run regular tasks during updates for you.
HoweverDo 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!
Danger
Zammad’s former scheduler.rb script has changed and is now called
background-worker.rb. Please ensure to reinstall the service - see
Step 6: Start Zammad or install as service!
- Step 1: Ensure dependencies
Before proceeding, double-check that your system environment matches Zammad’s requirements.
- Step 2: Stop Zammad and Clear Zammad cache
Before you continue, stop your Zammad processes.
$ rails r "Rails.cache.clear"
- Step 3: Download Zammad to your system
Get the latest stable release of Zammad here. This file will be updated whenever new bug-fixes are applied, so you can update from this URL regularly.
$ cd /opt $ wget https://ftp.zammad.com/zammad-latest.tar.gz $ tar -xzf zammad-latest.tar.gz --strip-components 1 -C zammad $ chown -R zammad:zammad zammad/ $ rm -f zammad-latest.tar.gz
For security reasons, ensure that your database configuration is readable for the Zammad user only.
$ chmod 600 /opt/zammad/config/database.yml $ chown zammad:zammad /opt/zammad/config/database.yml
- Step 4: Install Gems
$ su - zammad $ cd /opt/zammad $ gem install bundler
$ bundle install --without test development mysql
$ bundle install --without test development postgres
Danger
Support for MySQL/MariaDB will be dopped in Zammad 7.0 upwards. Make sure to migrate your existing instance of Zammad to PostgreSQL before that update.
Please have a look at our guide on how to migrate an existing MySQL/MariaDB instance to PostgreSQL: Migrate to PostgreSQL server.
- Step 5: Stop Zammad services
Stop the application server, websocket server and scheduler.
- Step 6: Upgrade your database
$ su - zammad $ rake db:migrate $ rake assets:precompile
- Step 7: Synchronize Zammad’s translation files
$ su - zammad # ignore if you haven't exited the Zammad user $ rails r "Locale.sync" $ rails r "Translation.sync"
- Step 8: Start Zammad services
Start the application server, web socket server and scheduler.
- Step 9: Log into Zammad
Yes, that’s it!
Warning
⚠️ Updates may require extra steps or introduce breaking changes.
Always check the upgrade notes first.
Note
🙀 Incomplete documentation
Sorry, but this documentation part is outdated. We will rework this part later, but can’t tell when yet.
Please feel welcome to provide a pull request if you find spare time!
$ docker-compose stop
$ git pull
$ docker-compose pull
$ docker-compose up
Start Zammad building Docker images locally with development branch
GIT_BRANCH=develop docker-compose -f docker-compose-build.yml up
Recreate locally built images
GIT_BRANCH=develop docker-compose -f docker-compose-build.yml build –no-cache
Open shell in running Zammad image
docker-compose exec zammad /bin/bash
Port compatibility error
The nginx container may have compatibility problems with other machines or services pointing to port 0.0.0.0:80. So to fix this, we’ll just have to modify the file docker-compose.override.yml and select different ports
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
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