Migrate Zammad to New Host

This is just a description of basic steps to perform a migration to a new host. Your environment may be different so you should consider this as a reference point only. If anything goes wrong, please consult the Zammad Community or consider paid support options.

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 in the relevant parts.

Hint

Migrating from Zammad SaaS? Skip to step 7. For restoration, you’ve received an attachment dump! 🤓

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.

Have a look at the installation instructions:

Step 3: Activate maintenance mode

This ends all agent and customer sessions. See here how to activate it.

Step 4: Disable your communication channels

The restore script starts Zammad automatically, this may help to avoid data loss and inconsistencies.

Step 5: Stop and disable Zammad

Make sure that no data will be changed before backing up.

$ systemctl disable zammad
$ systemctl stop zammad
Step 6: Backup

Follow the backup section to create your backup.

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

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

Step 7: Transfer your backup files

Save your backup files in a directory and provide the path to the config file. See backup configuration how to adjust the config file to your needs.

Step 8: Restore your backup

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

Be aware that restoring backups can overwrite your database.yml. You can check that by looking into the [...]_zammad_files.tar.gz file. If there is a database.yml in the directory config > database, ensure to save the original version before restoring.

In case it has been overwritten already, you can try the Database Helper: (Re)set Password.

Important:

Stop Zammad after the restoration has finished.

Step 9: Run required maintenance tasks after restoring

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

Step 9.1: Clear the cache
$ zammad run rails r "Rails.cache.clear"

Hint

Migrated from Zammad SaaS or switching provider?

Please make sure that your notification and FQDN configuration is correct.

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: Connecting Zammad with Elasticsearch 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 to log in again by disabling the maintenance mode.

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.

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