How to upgrade a Sapho on-premises Server

Audience: System administrators installing and configuring Sapho Server

In order to take advantage of all the new features we’re putting out with each release, you’ll occasionally need to upgrade your Sapho server. Following the steps below will make sure things go smoothly.

Step 1: Set up a staging server with the latest version of Sapho

Download the latest version of Sapho from https://www.sapho.com/try-sapho/ (or deploy in a virtual cloud using the deployment wizard on the site) and set up a staging server in your environment by following the bundled installation guide.

Step 2: Disable push notifications on the staging server

Set the following environment variable on the staging server:

SAPHO_DISABLE_NOTIFICATIONS=true

Step 3: Create a MySQL dump from the production server

Either run mysql dump from command line, e.g.

mysqldump --user=[your DB user] --host=[your production server DB URL] --protocol=tcp --port=3306 --default-character-set=utf8 --skip-triggers "sapho"

Or use a tool such as MySQL Workspace which has Data Export / Import support to dump database from production.

Step 4: Stop Tomcat on the staging server

Example:

service tomcat8 stop

Step 5: Copy the MySQL dump to the staging server

Drop the pre-existing Sapho database (DB) on the staging server and import the one from the production dump made in step 3. Again, this can be done using the CLI or a tool such as MySQL Workbench.

mysql --protocol=tcp --host=[your production server DB URL] --user=[your DB user] --port=3306 --default-character-set=utf8 --comments --database=sapho < "/path/to/dump-file.sql"

Step 6: Reconfigure the connectors on the staging server to point to the staging databases

The Sapho.service_jdbc table needs to be updated. Find and replace all instances of the source DB’s FQDN (pointing to production connectors) with the FQDN of the new DB instance (pointing to your test environment connectors).

Step 7: app_user_device and app_user table cleanup

Delete all records in the app_user_device table so that devices subscribed to the production server’s push notifications do not get notifications from the staging server.

Optionally, delete all records except the first one (root account) from the app_user table.

Step 8: Enable push notifications again (optional)

If you want to test push notifications on your test environment set

SAPHO_DISABLE_NOTIFICATIONS=false

Step 9: Upgrade staging server with the latest version of Sapho

Since we’ve applied production dump to staging environment Sapho on staging environment is not on latest version anymore hence we need to upgrade it to latest version again.

Step 10: Start Tomcat on staging server

Example command:

service tomcat8 start

Step 11: Test your apps on the staging server

Test your apps on the staging and server and be sure to test logging into and using the published version of your apps from either your mobile device or your browser in incognito mode. If there are problems, notify Sapho and stop at this step.

Step 12: Upgrade Sapho on production server

Test your apps on the staging and server and be sure to test logging into and using the published version of your apps from either your mobile device or your browser in incognito mode. If there are problems, notify Sapho and stop at this step.

  • Stop tomcat
  • Remove (for example) %catalina_home%/webapps/yoursaphoapp and %catalina_home%/webapps/yoursaphoapp.war
  • Drop in your new war file to %catalina_home%/webapps/ROOT.war
  • Restart tomcat

Step 13: Test your apps on the production

Test the apps on production and once again be sure to test logging into and using the published version of your apps from either your mobile device or your browser in incognito mode. If there are problems, restore MySQL using the DB dump from Step 3 and drop in a previous version of Sapho server using the procedure in Step 12. Contact Sapho for assistance.