Migrating Ubersmith 3.x to 4.x Estimated Reading Time: 7 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 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 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 Ubersmith config.ini.php file. The file’s location may vary by installation, but the default is found in /var/www/your.ubersmith.com. In the [maintenance] configuration block, set enabled=1 message=”Ubersmith is currently being migrated.” The message field can be set to any text you prefer. Verify that the old host has been placed into maintenance mode from your Ubersmith login page. Disabling Poll and Invoice Tasks On the old host, disable the daily invoicing and poll cron tasks by moving the files ubersmith and ubersmith_poll out of /etc/cron.d, or by editing the files to comment out the tasks within them. 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. Complete a logical export using mysqldump, which is likely already installed on the system. See the mysqldump documentation for MySQL 5.6. A binary export, which may be faster but more complicated to restore, can be performed using Percona’s xtrabackup, found in the Percona Toolkit. For simplicity, this documentation focuses on a logical backup. Example usage of mysqldump: mysqldump -u root -p ubersmith > ubersmith_export.sql In this command the root user logs into MySQL, the password is prompted for and entered on the command line, the ubersmith database is exported, and saved to a file named ubersmith_export.sql. Once the database export is complete, use the tail command to examine the end of the file to ensure it completed successfully. 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 Updating the Schema Running a schema update prior to starting the upgrade process improves the upgrade’s performance and allows it to complete in less time. Once the new host’s database import is complete, remain in the db container shell, and log into MySQL using the mysql command line client: mysql -u root -p$MYSQL_ROOT_PASSWORD ubersmith Run the following query: ALTER TABLE `ubersmith`.`inv_packs` ADD INDEX `packid` (`packid` ASC); Exit the database container shell by pressing CTRL D twice (once for mysql, second time for the shell). 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. Reconfiguring Ubersmith Email Settings In the Ubersmith web interface, go to Settings > Email Settings. For each brand configured in Ubersmith, change the Email sending settings options to use SMTP as the Method, and mail as the SMTP Host. SMTP Username and SMTP Password should be left blank. This configuration change allows Ubersmith to use the Postfix MTA running in the mail container.