Matomo has its own guide to migrating an instance to a new server. It suggest to do a new Matomo install on the new server. However, this means you also need to migrate your extra config info + plugins manually. That’s why I’m choosing for a simpler option with scp / ssh.
Step 1: Prepare the New Server
- Install Dependencies:
Ensure the new server has the necessary software installed to run Matomo:- Web server (Apache or Nginx)
- PHP (with required extensions)
- MySQL/MariaDB
- Create Database:
On the new server, create an empty MySQL database to hold the Matomo data:mysql -u root -p CREATE DATABASE new_matomo_db; GRANT ALL PRIVILEGES ON new_matomo_db.* TO 'db_user'@'localhost' IDENTIFIED BY 'your_password'; FLUSH PRIVILEGES;Replacenew_matomo_db,db_user, andyour_passwordwith your preferred database name, username, and password.
Step 2: Backup Matomo Files and Database on the Old Server
- Backup Matomo Files:
Usetarto create an archive of yourpublic_htmldirectory (or wherever Matomo is installed).tar -czf matomo_backup.tar.gz /path/to/public_html - Backup Database:
Usemysqldumpto export the Matomo database.mysqldump -u db_user -p db_name > matomo_db_backup.sqlReplacedb_useranddb_namewith the actual database credentials. - Transfer the Backup Files to the New Server:
You’ll need to securely copy the backup files to the new server usingscp. You will also need SSH key access between the old and new server to avoid password prompts.scp matomo_backup.tar.gz matomo_db_backup.sql user@destination:/path/to/destination
Step 3: Setup SSH Key Authentication Between Servers
- Generate SSH Key Pair on the Old Server:
If you don’t have an SSH key pair, generate one on the old server:This will generate a private and public key pair inssh-keygen -t ed25519 -C "[email protected]"~/.ssh/id_ed25519.pub (by default). - Copy Public Key to the New Server:
Usessh-copy-idto copy the public key to the new server:ssh-copy-id user@destinationThis command will prompt you for the password of the new server once and then allow passwordless SSH access between the old server and the new server. - Test SSH Access:
Test that you can SSH into the new server from the old one without a password prompt:ssh user@destination
Step 4: Transfer Matomo Files and Database to the New Server
- Transfer the Files:
Extract the backup files into the correct directory on the new server (e.g.,/var/www/htmlor/path/to/destination).tar -xzvf matomo_backup.tar.gz -C /path/to/destination - Restore the Database:
Import the database dump into the new MySQL database:mysql -u db_user -p new_matomo_db < matomo_db_backup.sql
Step 5: Update Configuration Files on the New Server
- Edit Database Connection Details:
On the new server, open the Matomoconfig/config.ini.phpfile and update the database connection details if they are different:iniKopiërenBewerken[database] host = "localhost" username = "db_user" password = "your_password" database = "new_matomo_db"Replacedb_user,your_password, andnew_matomo_dbwith the actual credentials. - Check File Permissions:
Ensure that the file and directory permissions are correct so that Matomo can function properly:chown -R www-data:www-data /path/to/matomo chmod -R 755 /path/to/matomo
Step 6: Final Server Configuration
- Cron Jobs:
If you are using cron jobs for Matomo (e.g., archiving), ensure they are set up on the new server. Example cron job to run every 5 minutes:*/5 * * * * php /path/to/matomo/console core:archive - Test Matomo Installation:
After the migration, open Matomo in your web browser and check that everything works, including:- Tracking data
- Reports
- Plugins
Step 7: Remove SSH Key Access from the New Server
After the migration is complete and you’ve confirmed everything is working on the new server, you can remove the SSH keys from the new server for added security.
- Delete the Old Server’s SSH Key from the New Server’s
authorized_keys:
On the new server, remove the old server’s SSH public key from the~/.ssh/authorized_keysfile:nano ~/.ssh/authorized_keysFind and delete the line containing the old server’s public key. - Test Removal of SSH Key Access:
Attempt to SSH into the new server from the old server to confirm that access is no longer allowed:ssh user@destinationYou should be prompted for a password (indicating the key has been removed).
Step 8: Update DNS and Final Configurations
- Update DNS Records:
If Matomo is hosted under a domain or subdomain, update the DNS records to point to the new server’s IP address. - Remove the Old Server:
Once you’ve verified everything is working and DNS has propagated, you can decommission the old server.
Also at the new server go to Settings > Diagnostics to see if it’s all setup properly and whether Matomo detects security issues that need fixing.
Conclusion
You’ve successfully migrated your Matomo installation from one server to another, including:
- Backing up and transferring files and databases
- Setting up SSH key authentication
- Testing the installation on the new server
- Removing the old server’s SSH key for security
By following these steps, you should now have Matomo running on the new server without any issues!
Last Updated on 2 May 2025
