Upgrading Convention Master

Basic overview

Preliminary

As with all Convention Master upgrades, the basic premise is the same:

1. Check the requirements
2. Read the release notes
3. Back up existing files and the database
4. Pull in the new files
5. Log in to console with a privileged account to trigger the database update script
6. Test the update

Check requirements

Convention Master 10.1.7 requires:

• PHP 8.1.x (End of Life Dec 1, 2019) or later
• MySQL 5.5, 5.6, or 5.7

Recommended Baseline for new servers

• Ubuntu 22.04 LTS
• PHP 8.1.x
• MySQL 8.0

For more information, please read the Manual/Installation requirements. For MySQL 8.0 specifically, see Setting up Mysql 8.

Configuration Requirements as of version 10.1.0

Version 10.1.0 requires PHP 7.x version 7.1 or later. We recommend using a currently supported version of PHP such as 7.3 or 7.4. We have not validated PHP 8 at this time.

Version 10.1.0 adds an entirely new system for payment processing that supports more providers such as Square and Stripe. It should automatically update your current provider API keys to the new payment system but you will need to enable the payment providers manually in each kiosk you accept payments. If you have any questions please reach out to support.

The manually configured file-based (steps.inc.php) kiosks are deprecated and you should migrate to DB configured kiosks as part of this upgrade if you have not already. To check if you have any file-based kiosks you can go to Admin-Event -> Kiosks in staff console. If it says the status is "In Use" and there is no Edit button then it is a file-based kiosk.

It is important to verify the payment step settings on every kiosk after upgrading to version 10.1.0 - otherwise you will not be able to collect payments.

Configuration Requirements as of version 10.0.0

Upgrading existing Convention Master 9.5.0 installs running on PHP 5.6 to version 10.0.0 does not require any special changes.

Version 10.0.0 adds PHP 7 support and part of that was upgrading the license system. If you run Convention Master on PHP 7 or later you will need to have a new license file from the License Center.

The old License File format is supported on PHP 5.6 only. The new license files will work on any PHP version and we recommend swapping them in if you have the chance.

Configuration Requirements as of version 9.5.0

Version 9.5.0 introduced a new feature allowing Kiosks to be configured from the console. These database configured kiosks need a special URL rewrite rule to function properly. In order for this to function, your Apache vhost configuration file must allow .htaccess file overrides. For instructions on enabling this in Apache, see Manual/How to enable Mod Rewrite for new kiosks

Read the release notes

The release notes for the current release can be found here: 10.0.12

Back up existing files and the database

Full instructions: Manual/Backing up Convention Master

While the upgrade scripts are well-maintained and robust, things could still go awry. Before proceeding to update Convention Master and the database schema, make a full backup of Convention Master, including both the database and the files:

• Convention Master's database:

• MySQL, do a SQL dump with the mysqldump command:

mysqldump --user=db_user --password=db_userpassword convention_master_db > file.sql

• Make sure you move that backup file to a safe location where it won't be deleted or accessable by web.

• Convention Master's files:

• tar, compress all files into a backup file with the tar command:

tar -cvpzf backup.tar.gz --exclude=/backup.tar.gz /path/to/your/installation/ 

• Make sure you move that backup file to a safe location where it won't be deleted or accessable by web.

Pull in the new files

Command line

You may need to run the svn command as sudo if you don't have full write permissions to the Convention Master install directory under your current user. When running the svn command, it will replace the files with updated versions inside the installation directory:

$ cd /path/to/your/installation/  
$ svn up .

Log in to console with a privileged account to trigger the database update script

Now that you have pulled in the new version, you need to log in to the staff console with a privileged account to trigger the database update scripts. Once you enter your username and password on the login screen, it may take a minute or two for the page to load. This is the system running any database upgrades in the release. When it loads, you should see a box with information that your database has been upgraded to version ###. If there were any issues during the database upgrade they will be logged. Please contact Convention Master support if a database upgrade fails.

Note: Once you pull in the new files, your Convention Master install will automatically go into maintenance mode to prevent any changes to the database until you trigger the database update script.

To trigger the database update script, login to the /console directory in your browser. The login account requires the SYSTEM_UPGRADE permission. Example url:

https://demo.civetsolutions.com/console

What to do in case of "Unable to obtain bruteforce lockout information" error (or similar) on console login screen

This error appears on the console login page in a red box and the actual login fields will be missing.

Cause: If you are connecting to an existing old database file and are now running on MySQL version 5.7+ it is possible that you will miss the checks in /setup that detects incompatible default MySQL configurations introduced in MySQL version 5.7+

You are unlikely to experience this issue when upgrading unless you are setting up a new server at the same time and using MySQL version 5.7+ for the first time.

The best way to resolve this issue is to temporarily rename your /shared_php/db_connect.inc.php file to something else and navigate to the setup folder in your browser. It should verify your MySQL configuration and inform you how to do any needed changes.

Test the update

Once the upgrade has been completed, browse Convention Master and check that the following operations work as expected:

• console pages
• kiosks that you previously set up
• send yourself a test email (In the console menu as: Admin Install - Edit Email Servers )

Frequently asked questions

How hard is it to upgrade?

If the only existing files you have modified are configuration files like db_connect.inc.php or steps.inc.php and you are upgrading from 9.0.0 or later, the process is very simple. The amount of human work involved is only a few minutes. The database schema changes will take an amount of time proportional to the size of your database — potentially minutes for conventions with millions of attendees, but for a more typical size, it is usually done in seconds.

Upgrading becomes difficult if you have modified our source code, and you don't want your changes to be overwritten.

How do I upgrade from a really old version? In one step, or in several steps?

It depends: If you are upgrading from Convention Master 8.2.10 or older, you should upgrade to Convention Master 9.0.0 first.

If you are upgrading from Convention Master 9.0.0 or newer, you can upgrade in one step, from your old version to the latest version.

Should I back up first?

Short answer: Yes.

Long answer: It depends on a) how much you value your data, b) how hard it is to create a backup and c) how confident you are with MySQL maintenance and administration. We are not responsible for any data loss incurred by an upgrade. Backups are important.

An upgrade failure may leave your database in an inconsistent state, in between two versions. A PHP or MySQL error might happen during upgrade leaving your database partly upgraded. In such situations, it may be possible to somehow fix this problem with much manual work. However, it will be way easier to just put a database backup from before running the update in place and to continue with that. Otherwise, you might have hours of - needless - work.

Recovery is often complex. Volunteers on the support chats are unlikely to be impressed if you neglect to make a backup and then need help to recover from upgrade-related corruption. A better outcome is if you can revert to your backup, and then report to Convention Master support the bug in the upgrade process which caused the corruption.

Can I keep my db_connect.inc.php?

Yes, but you may have to make some minor changes. The format of db_connect.inc is largely backward compatible. Changes which break db_connect.inc.php compatibility will be documented in the "configuration changes" section of the release notes.

Can my Convention Master stay online while it is upgrading?

Generally yes, however, SVN may temporarily (for a few seconds) break it. However, once you pull in the new files, your Convention Master install will automatically go into maintenance mode to prevent any changes to the database until you trigger the database update script. If you're quick about it, it should only be a few minutes of "downtime".

Why upgrade?

Because it's usually easy enough and a single step from your version to latest].

Recent releases receive security fixes to keep your install and your host safe from vandals, while old releases don't. That makes dozens of good reasons to upgrade!

New major releases come with new features, which you might want to use: see the release notes for details.