Migrating Ubersmith 4.x to 4.x 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/ubersmithIf 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 MigrationPerform these steps before migration day.Ensuring ConnectivityEnsure 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 HostEnsure 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/ubersmithdocker-compose rm -sf cron mailTransferring CertificatesIf 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/sslEnsure 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/ubersmithdocker-compose restart webdocker-compose up -d mailIf the services do not start properly, review the container logs in: /var/log/ubersmith/web/docker.log /var/log/ubersmith/mail/docker.logIf 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 RunTo 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 dumpDatabase transferDatabase restoreUbersmith upgradeBased 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 DayThese steps perform the migration and will cause Ubersmith to be unavailable.Putting Old Host into Maintenance ModeNotify 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/ubersmithdocker-compose up -d webVerify that the old host has been placed into maintenance mode by accessing your Ubersmith login page.Disabling Poll and Invoice TasksOn the old host, disable the daily invoicing and poll cron tasks by running the following command:cd /usr/local/ubersmithdocker-compose rm -sf cron mailDisabling these tasks ensures that the old host does not poll your infrastructure or generate invoices once the migration is complete.Exporting the DatabaseBy 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/ubersmithdocker-compose exec db bashmysqldump -u root -p$MYSQL_ROOT_PASSWORD ubersmith > /ubersmith_export.sqlThis 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/backupdocker 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/backuptail -n1 ubersmith_export.sqlA successful completion will show the output -- Dump completed on with a date and timestamp.Copying the DatabaseCopy 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 bashWithin the new host’s shell in the database container, restore the database:mysql -u root -p$MYSQL_ROOT_PASSWORD ubersmith < /ubersmith_export.sqlAnother method, which provides a progress meter:pv /ubersmith_export.sql | mysql -u root -p$MYSQL_ROOT_PASSWORD ubersmithUpgrading UbersmithDuring 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/ubersmithdocker-compose exec php bashWithin the PHP container, run the upgrade command:php /var/www/ubersmith_root/app/www/setup/updatedb.php ubersmith --debugThe 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/setupThis 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 MigrationThese steps finalize the migration and move Ubersmith to the new host.Enabling Scheduled Tasks and MailOn the new host, recreate the cron and mail containers, so that Ubersmith can receive and send mail and perform scheduled tasks.cd /usr/local/ubersmithdocker-compose up -d cron mailUpdate 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 LicenseWhen you are satisfied that Ubersmith is functioning properly, contact Ubersmith Support to remove the additional license from your account.