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 restoring. 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. For restoration, you’ve received an attachment dump! 🤓

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 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 between these installation types:
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
Step 6: Backup!

Follow our documentation part for backup creation.

Remember 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 config file in 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.

If you’re running a source code installation, we recommend install the same version beforehand. This reduces environment fiddling a lot.

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.

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 "Rails.cache.clear"
Step 10: Apply missing environmental settings

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.

Hint

Migrated from Zammad SaaS or switching providers?

Please make sure that your notification and FQDN configuration is still correct. Other wise you may have unexpected issues like not receiving notifications or non functional authentications (3rd party).

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.