Migrate Zammad to new host

🙅‍♀️ This is a proof of concept, not a full how to. Your environment may be different.

Please note that the steps described on this page are an addition to backing up and restoration.

They’re not meant to stand alone - we’ll link and note this at the relevant parts.

If anything goes wrong, please consult the Zammad Community or consider paid support options.


Hint

Migrating from Zammad SaaS? Skip to step 7.

Step 1: Note down your environmental adjustments

This mainly affects performance tuning settings. This will be important after restoring.

Step 2: Install Zammad on the destination host

For the easiest restoration path possible, please install the same version like your origin instance. You could also consider updating the old instance before migrating.

Choose beetween these installation types:
  • package

  • source code

  • docker-compose

    Warning

    Restoration & Migration on docker based installation may differ. While the steps are the same on most parts, it is not covered by this documentation!

Step 3: Activate maintenance mode

This ends agents and customers sessions. Learn more about the maintenance mode in Zammad.

Step 4: Disable your communication channels

This is just a safety measurement. As our restore scripts starts Zammad automatically, this may help if something is not in a correct state.

Step 5: Stop and disable Zammad

Make sure to no longer have Zammad change data before backing up.

$ systemctl disable zammad
$ systemctl stop zammad

Note

This does not apply to docker based environments.

Step 6: Backup!

Follow our documentation part for backup creation.

Hint

Note down if you’ve created a full filesystem dump or only backed up your attachments. This will be important for the restoration.

If you want to go with the easiest way, consider only dumping your attachments. Learn more on our configuration page.

Step 7: Transfer your backup files

You’ll find the backup location within the conf file on the backup directory. Make sure to adjust the backup configuration on the destination host according to our configuration page to provide the correct backup file directory.

Provide the file location you transferred the backup files to.

Step 8: Restore your backup

Follow the steps 1 to 3 of our restoration page to restore the backup on the new host.

Warning

If you’re running a source code installation, install the same version before hand. This reduces environment fiddlings a lot.

If you don’t want that, you can find a version list on the Software page.

Warning

Restoring old backups may overwrite your database.yml. You can find out if that’s the case by having a look into the file .tar.gz within the config directory. If you can see a database.yml there, ensure to save the original version before restoring.

If you found the trap already, you can try the Database Helper: (re)set password.

Important

Stop Zammad after the restoration has finished.

If you experience issues during restoration, please consult Troubleshooting Backup & Restore.

Step 9: Run required maintenance tasks after restoring

After successful restoration, please continue below depending if you’ve only backed up your attachments or had a full filesystem dump.

Tip

Migrating from Zammad SaaS? You’ve received an attachment dump! 🤓

Note

Keep in mind that docker-compose and source code installations do not know zammad run. Below commands show the package installation way, just remove all zammad run parts from the commands and run them.

This means: zammad run rails c would be rails c.

Step 9.1: Clear the cache
$ zammad run rails r "Cache.clear"
Step 10: Apply missing environmental settings

Note

This does not apply to Docker images, as the following settings should be applied upon every start automatically.

If you’ve set any environmental settings like higher web concurrency due to required 🎛️ Performance Tuning, please re-apply your settings now.

If not already done, please install Elasticsearch now (if you want to use it). Follow Step 3: Connect Zammad to reconfigure your installation for Elasticsearch use and rebuild the search index.

You are now ready to continue your work. The rebuild of your search index can safely run during your work, but will cause a degraded search performance and may lead to temporarily not found data.

Step 11: Re-enable Channels and deactivate maintenance mode

Set the previous deactivated channels back to active if you’re sure everything was successful. At this point Zammad will start to change data!

After verifying the functionality of your channels, allow your agents and customers back in by disabling the maintenance mode.

Learn more about the maintenance mode in Zammad.

Step 12 (optional): Update Zammad to latest possible version

In case the backup source was not on the latest possible version, please update your Zammad installation now.

In case your installed version is fairly old, please note the upgrade path notes on our updating zammad page.