Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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

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 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.

Panel
borderColor#8181AA
bgColor#FDFDFD
titleColor#8181AA
titleBGColor#2F304F
borderStylesolid
titleOn this page:

On this page:

Table of Contents
indent10px

Page properties
hiddentrue
Document Stage
Audience
Author
Reviewer
Created Date
Updated Date
Version
Links
Graphics