Migrating Ubersmith 4.x to Latest Release Estimated Reading Time: 6 Minutes Read this document completely before starting the migration process, to ensure the necessary access is available to complete all steps. For these steps, the new host is the system Ubersmith is being migrated to, and the old host is the system Ubersmith is being migrated from. It is also assumed that Ubersmith will be installed to the following default directory: /usr/local/ubersmith If you would prefer to have Ubersmith perform your migration, please contact Ubersmith Support to discuss the scope of the project and to arrange for a quote from our Managed Services team. Preparing for the Migration Perform these steps before migration day. Ensuring Connectivity Ensure that the old host can reach the new host via SSH. Configure an SSH key between the two hosts to ease file copying and database dumps. See this online resource to perform this configuration task. Deploying the New Ubersmith Host Ensure that the new host system is compatible with Ubersmith and install the Ubersmith Installation and Upgrade Utility prerequisites. Deploy Ubersmith on the new host using the Ubersmith Ubersmith Installation and Upgrade Utility. Once the installation is complete, disable the cron and mail containers on the new host environment. This ensures that the new system does not send any outgoing mail or process any recurring tasks until it is ready to go into production. cd /usr/local/ubersmith docker-compose rm -sf cron mail Transferring Certificates If the old host has certificates to use to secure HTTPS and SMTP connections to Ubersmith copy them to the new host and place them into: /usr/local/ubersmith/conf/ssl Ensure that the certificate and key filenames match the SSLCertificateFile and SSLCertificateKeyFile directives in the Apache Virtual Host definition, in /usr/local/ubersmith/conf/httpd/sites-enabled. The leading paths will be different; it is only necessary to ensure that the filenames are the same. Ensure that the certificate and key filenames match the volumes configuration for the mail service in /usr/local/ubersmith/docker-compose.override.yml. Restart the web and mail services to ensure they start properly with the certificates configured: cd /usr/local/ubersmith docker-compose restart web docker-compose up -d mail If the services do not start properly, review the container logs in: /var/log/ubersmith/web/docker.log /var/log/ubersmith/mail/docker.log If the log files are not available, you may need to restart rsyslog on the new host to use the Ubersmith-specific configuration file. Scheduling Downtime/Dry Run To get a time estimate of how long Ubersmith will be offline, perform a dry run by performing the migration day steps, but not the post migration steps. Note the timing for the following events: Database dump Database transfer Database restore Ubersmith upgrade Based on the details of the dry run, schedule downtime with your users. For extended downtime, consider performing the migration after hours or on a weekend. Contact Ubersmith Support to arrange for a temporary license for the new host. Migration Day These steps perform the migration and will cause Ubersmith to be unavailable. Putting Old Host into Maintenance Mode Notify users that the Ubersmith migration is about to begin, so they can complete any current tasks. Place the old host into maintenance mode by modifying the docker-compose.yml file. The file’s location may vary by installation, but the default is found in /usr/local/ubersmith. From the web service configuration block, in the environment section, set the MAINTENANCE variable to 1, and recreate the web container by running: cd /usr/local/ubersmith docker compose up -d web Verify that the old host has been placed into maintenance mode by accessing your Ubersmith login page. Disabling Poll and Invoice Tasks On the old host, disable the daily invoicing and poll cron tasks by running the following command: cd /usr/local/ubersmith docker-compose rm -sf cron mail Disabling these tasks ensures that the old host does not poll your infrastructure or generate invoices once the migration is complete. Exporting the Database By default, the Ubersmith database is named ubersmith and is stored in the db container. Ensure your host has enough available disk space to store both the running copy of the database, and two copies of the backup you will create. There are many ways to perform a database dump, some more efficient than the method described here; however using mysqldump is one of the easiest approaches. See the mysqldump documentation for MySQL 5.7. Perform a backup by entering a shell in the db container, and then run mysqldump: cd /usr/local/ubersmith docker-compose exec db bash mysqldump -u root -p$MYSQL_ROOT_PASSWORD ubersmith > /ubersmith_export.sql This command logs into MySQL as the root user, the password is supplied by an environment variable, and the ubersmith database is exported and saved to a file in the filesystem root named ubersmith_export.sql. Once the database export is complete, use the exit command to leave the db container's shell. Use the docker cp command to copy the database dump out of the container's filesystem. cd /usr/local/ubersmith/backup docker cp ubersmith_db_1:/ubersmith_export.sql . Use the tail command to examine the end of the file to ensure it completed successfully. cd /usr/local/ubersmith/backup tail -n1 ubersmith_export.sql A successful completion will show the output -- Dump completed on with a date and timestamp. Copying the Database Copy the database export file from the old host to the new host, using scp or sftp. Copy the database export file into the new host’s db container, using the docker cp command: docker cp ubersmith_export.sql ubersmith_db_1:/ Enter a shell in the new host database container (db) to begin the restore: cd /usr/local/ubersmith; docker-compose exec db bash Within the new host’s shell in the database container, restore the database: mysql -u root -p$MYSQL_ROOT_PASSWORD ubersmith < /ubersmith_export.sql Another method, which provides a progress meter: pv /ubersmith_export.sql | mysql -u root -p$MYSQL_ROOT_PASSWORD ubersmith Upgrading Ubersmith During your dry run, if you determined that the upgrade process takes a significant amount of time, consider running the upgrade process in screen or tmux, in the event you lose your connection to the new host. On the new host, enter a shell in the PHP container (php) to begin the upgrade. cd /usr/local/ubersmith docker-compose exec php bash Within the PHP container, run the upgrade command: php /var/www/ubersmith_root/app/www/setup/updatedb.php ubersmith --debug The upgrade process can take several hours to complete depending on the size of your installation. When complete, the upgrade command will output Done. When the upgrade process is complete on the new host, still within the PHP container shell, run: rm -rf /var/www/ubersmith_root/app/www/setup This takes Ubersmith out of Setup mode. Verify that Ubersmith is online and has been issued a token, and that the login screen is present. Post Migration These steps finalize the migration and move Ubersmith to the new host. Enabling Scheduled Tasks and Mail On the new host, recreate the cron and mail containers, so that Ubersmith can receive and send mail and perform scheduled tasks. cd /usr/local/ubersmith docker-compose up -d cron mail Update entries for your existing Ubersmith DNS records to resolve to the IP for the new host. Verify that incoming mail is functioning by sending a test email to the Support Manager and examining the log file at /var/log/ubersmith/mail/docker.log. Removing Temporary License When you are satisfied that Ubersmith is functioning properly, contact Ubersmith Support to remove the additional license from your account.