Upgrading to Jadu CMS 21.0.0

Non-backwards compatible changes

Database schema changes

MariaDB 10.5 introduces a new reserved word “rows”. References to “rows” have been renamed in Jadu CMS database schema to ensure ongoing compatibility:

Renamed JaduHomepages.rows to JaduHomepages.pageRows

File changes

The following files have been moved and their PHP namespace updated:

Jadu\Category\Event\Object\Delete.php -> Jadu\Category\Event\Model\Delete.php
Jadu\Category\Event\Object\Move.php -> Jadu\Category\Event\Model\Move.php

Other changes

Database schema changes

MariaDB 10.5 compatibility has required changes to default values in our database schema. JaduContentTypes was previously set to not allow null values, it now has a default value of empty string set.

As strict mode is enabled by default in MariaDB 10.5, and the timestamp “1970-01-01 00:00:00” is reserved, our code has been updated to address this.

File changes

Galaxies sites’ SSL configuration for Apache configuration has been moved into a separate configuration file, microsites/templates/apache/ssl_block.cfg, to allow easier maintenance and configuration within the customer's environments.

Directory permission changes when using 2021 Installer

User permissions are no longer granted on the base 'logs' directory, instead permissions are explicitly granted on individual sub-folders.

Testing Compatibility PHP 7.4

New versions of the PHP programming language are regularly released and older versions are retired. It’s important to check compatibility of your code with the new PHP version as the language does evolve and change, functions and syntax your code uses may no longer be available in the new version. You can use code sniffers to check your code for compatibility with a particular version.

Install PHP CodeSniffer

Begin by installing PHP CodeSniffer following the instructions in the project README on GitHub.

Checkout code from repository (if using)

If your code is committed to a repository, checkout the code to your local file system.

Run the PHP CodeSniffer

Run the following command to check compatibility. Where [php-version] is replaced with the PHP version e.g. 7.4

php -d memory_limit=-1 /path/to/phpcs.phar -p --ignore="*/vendor/*" --extensions=php --runtime-set testVersion [php-version] --standard=PHPCompatibility /path/to/repository/

An example of the command to check for compatibility with PHP 7.4

php -d memory_limit=-1 /path/to/phpcs.phar -p --ignore="*/vendor/*" --extensions=php --runtime-set testVersion 7.4 --standard=PHPCompatibility /path/to/repository/

Analysing the results

The command will output results similar to

$ php -d memory_limit=-1 /path/to/phpcs.phar -p --ignore="*/vendor/*" --extensions=php --runtime-set testVersion 7.4 --standard=PHPCompatibility /path/to/repository/    
............................................................   60 / 1981 (3%)
............................................................  120 / 1981 (6%)
............................................................  180 / 1981 (9%)
............................................................  240 / 1981 (12%)
............................................................  300 / 1981 (15%)
............................................................  360 / 1981 (18%)
............................................................  420 / 1981 (21%)
............................................................  480 / 1981 (24%)
................................W...........................  540 / 1981 (27%)
............................................................  600 / 1981 (30%)
............................................................  660 / 1981 (33%)
............................................................  720 / 1981 (36%)
............................................................  780 / 1981 (39%)
............................................................  840 / 1981 (42%)
............................................................  900 / 1981 (45%)
............................................................  960 / 1981 (48%)
............................................................ 1020 / 1981 (51%)
............................................................ 1080 / 1981 (55%)
............................................................ 1140 / 1981 (58%)
............................................................ 1200 / 1981 (61%)
............................................................ 1260 / 1981 (64%)
............................................................ 1320 / 1981 (67%)
............................................................ 1380 / 1981 (70%)
............................................................ 1440 / 1981 (73%)
............................................................ 1500 / 1981 (76%)
............................................................ 1560 / 1981 (79%)
............................................................ 1620 / 1981 (82%)
............................................................ 1680 / 1981 (85%)
..............................W............................. 1740 / 1981 (88%)
............................................................ 1800 / 1981 (91%)
............................................................ 1860 / 1981 (94%)
..........W................................................. 1920 / 1981 (97%)
............................................................ 1980 / 1981 (100%)
.                                                            1981 / 1981 (100%)



FILE: /path/to/jadu/XFormsPro/Form/Advanced/Logics/LogicInputRetracer.php
--------------------------------------------------------------------------------------------
FOUND 0 ERRORS AND 1 WARNING AFFECTING 1 LINE
--------------------------------------------------------------------------------------------
 1 | WARNING | No PHP code was found in this file and short open tags are not allowed by this install of PHP. This file may be using short open tags but PHP does not allow them.
--------------------------------------------------------------------------------------------


FILE: /path/to/jadu/XFormsPro/BlueBadge/Resolver/BlueBadgeApplicationResolver.php
----------------------------------------------------------------------------------------------------
FOUND 0 ERRORS AND 1 WARNING AFFECTING 1 LINE
----------------------------------------------------------------------------------------------------
 1148 | WARNING | The left-associativity of the ternary operator has been deprecated in PHP 7.4. Multiple consecutive ternaries detected. Use parenthesis to clarify the order in which the operations should be executed
----------------------------------------------------------------------------------------------------


FILE: /path/to/jadu/XFormsPro/Workflow/WorkflowService.php
-----------------------------------------------------------------------------
FOUND 0 ERRORS AND 1 WARNING AFFECTING 1 LINE
-----------------------------------------------------------------------------
 1 | WARNING | No PHP code was found in this file and short open tags are not allowed by this install of PHP. This file may be using short open tags but PHP does not allow them.
-----------------------------------------------------------------------------

Time: 26.42 secs; Memory: 28MB

Verify each warning and error that has been output and correct as required.

The PHP project provides guides for migrating from one version to another version which can be used for reference https://www.php.net/manual/en/appendices.php

Windows Server 2019 Upgrade Guidance Note

This document provides high-level guidance to customers that undertake their own hosting and management of Jadu software running on a WISP (Windows Server 2016, SQL Server, IIS 10, PHP 7.2) server software stack and wish to undertake an upgrade to Windows Server 2019, SQL Server 2019, IIS 10, PHP 7.4.

This document provides guidance to system administrators, and is not intended as a universal step by step guide - if such a level of support is required, please contact Jadu for a professional services quotation.

Overall Approach

In order to upgrade your platform, you will need a new server running Windows Server 2019. The upgrade will copy the database and some of the file systems from the old server to the new server. Some amount of service downtime is expected during the migration process.

This guide applies to sites running Photon and Classic front ends as well as sites with and without Jadu XFP. Any differences for a particular configuration will be highlighted at the relevant point.

Note: At the time this document was created (July 2021) Jadu software does not support PHP versions above 7.4, SQL Server versions above 2019 or Windows versions above 2019.

1. Setup new servers

You will need to commission new servers for the upgrade. Full details on setting up Windows Servers can be found in Jadu CMS WISP Installation guide. After installing the CMS, XFP customers will need to install XFP using the XFP installation guide.

Ensure you can log into the Control Center after installation.

2. Backup content from old Windows Server

2a. Backup databases

Log into the old database server and take a backup of the database(s). You will need to take backups of the main Jadu database (typically called jadudb or jadu) as well as databases for galaxies sites (these databases are typically prefixed with ms_).

Use SQL Management Studio to take the backups. Make a note of the backup destination.

2b. Backup directories

Along with the database, some content is stored on the file system. Compress the following directories into zip files for easy transfer.

Replace /path/to/jadu with the root directory of your jadu installation, this is typically C:/inetpub/wwwroot/jadu.

Directory	Notes
/path/to/jadu/public_html	Contains the web accessible scripts and content
/path/to/jadu/var	Contains non web accessible content.
/path/to/jadu/config	Contains the site configuration files
/path/to/jadu/jadu/custom	Contains custom code (if exists)
/path/to/jadu/src	Contains site code
/path/to/jadu/microsites	Contains scripts for galaxies sites.
/path/to/jadu/jadu/PayBridge/PSP/Adapter	PayBridge PSP adapters (if using PayBridge)
/path/to/jadu/PAYBRIDGE_*	PayBridge adapter version files (if using PayBridge)
/path/to/jadu/.meteor/file-migrations	Contains history of file migrations run by patching

Either use built in windows compressed zip functionality to backup the directories or your preferred compression software.

3. Copy content to new server

Download the backups from the source server and transfer to a directory on the new server outside of the Jadu root installation directory e.g. C:/JaduMigration and extract to this directory.

4. Update Database

Open SQL Server Management Studio on the new server.

4a. Take the jadudb database offline.

The database needs to be taken offline to restore.

4b. Restore jadudb database from the backup.

Once the database is offline, restore it from the backup.

Under the General page, choose Device under source and select the database backup file you copied to the server.

Under the Options page, tick Overwrite the existing database (WITH REPLACE) option under Restore options.

Click Ok to restore the database

4c. Restore Galaxies Site databases.

If the site you are migrating has galaxies sites databases, restore these databases as well. Galaxies sites databases won’t exist on the new server so a simple restore will suffice for these databases.

As before, select Device under the Source options and select the database backup file. You do not need to tick Overwrite the existing database (WITH REPLACE) when restoring a galaxies site database as the database will not already exist.

Once all databases have been restored continue with the migration.

5. Update File System Content

Restore the file system content by unzipping the zipped folders exported from the source server.

Copy the unzipped folders (except config) into the corresponding locations in the jadu installation directory.

Folder	Destination
public_html	/path/to/jadu/public_html
var	/path/to/jadu/var
custom	/path/to/jadu/jadu/custom
src	/path/to/jadu/src
microsites	/path/to/jadu/microsites
Adapter	/path/to/jadu/jadu/PayBridge/PSP/Adapter
PAYBRIDGE_*	/path/to/jadu
file-migrations	/path/to/jadu/.meteor

When copying public_html you’ll be warned that there is a folder with the same name as the file name you specified related to blogImages.

Skip the file and continue the copy.

When prompted to Replace or Skip Files, choose to Replace the files in the destination.

If you have installed PHP on the new server in a different location to where it was installed on the old server you will need to update the paths to the PHP executable in the batch files under var/scheduled_tasks/ to the new path of the PHP executable.

6. Update database permissions

Open SQL Server Management Studio on the new server.

6a. Add database users

Under Security > Logins find the jadu, jaduGM and jaduGU users.

Right click and choose Properties on the jadu user. Under User Mapping select the jadudb and enable database roles db_datareader, db_datawriter, db_ddladmin and public.

Click OK to save.

Repeat updating the user mapping for both the jaduGM and jaduGU users.

jaduGM should be given the following roles:

Database	Roles
jadudb	db_datareader db_datawriter db_ddladmin public
ms_*	db_datareader db_datawriter db_ddladmin db_owner public

jaduGU should be given the following roles:

Database	Roles
jadudb	db_datareader db_datawriter db_ddladmin public
ms_*	db_datareader db_datawriter db_ddladmin public

6b. Remove imported database users

When the database was imported it imported the database users from the source server. Remove these users by navigating to Databases > jadudb > Security > Users.

The new site will use users jadu, jaduGM and jaduGU. Remove the imported users JaduUser, GalMgr and GalUser by right clicking and choosing delete.

If you are unsure which users to delete you can check the usernames against the source database.

You should also remove the users from the ms_* databases using the same process. When removing the GalUser from the galaxies site database you may encounter an error where the user cannot be removed because The Database Principal Owns A Fulltext Catalog In the Database, and Cannot Be Dropped.

To resolve this, navigate to Storage > Full Text Catalogs on the ms_ database and open the properties of the indexes. Check the owner property of the index and update the owner to jaduGU and save.

Now you should be able to delete the user.

6c. Update permissions on Certificates and Keys

We now need to grant permission on the Jadu Certificate and Jadu Key to the updated database users.

Run the SQL statements to update the permissions on the certificate and key on the jadudb database.

-- Grant View
GRANT VIEW DEFINITION ON CERTIFICATE::JaduCertificate TO jadu
GRANT VIEW DEFINITION ON SYMMETRIC KEY::JaduKey TO jadu
GRANT VIEW DEFINITION ON CERTIFICATE::JaduCertificate TO jaduGM
GRANT VIEW DEFINITION ON SYMMETRIC KEY::JaduKey TO jaduGM
GRANT VIEW DEFINITION ON CERTIFICATE::JaduCertificate TO jaduGU
GRANT VIEW DEFINITION ON SYMMETRIC KEY::JaduKey TO jaduGU

-- Grant Control
GRANT CONTROL ON CERTIFICATE::JaduCertificate TO jadu
GRANT CONTROL ON CERTIFICATE::JaduCertificate TO jaduGM
GRANT CONTROL ON CERTIFICATE::JaduCertificate TO jaduGU

For each ms_* database run the SQL statements

-- Grant View
GRANT VIEW DEFINITION ON CERTIFICATE::JaduCertificate TO jaduGM
GRANT VIEW DEFINITION ON SYMMETRIC KEY::JaduKey TO jaduGM
GRANT VIEW DEFINITION ON CERTIFICATE::JaduCertificate TO jaduGU
GRANT VIEW DEFINITION ON SYMMETRIC KEY::JaduKey TO jaduGU

-- Grant Control
GRANT CONTROL ON CERTIFICATE::JaduCertificate TO jaduGM
GRANT CONTROL ON CERTIFICATE::JaduCertificate TO jaduGU

7. Update configuration

You now need to update the site configuration. In step 5 we extracted the config directory but didn’t copy the contents of the extracted directory over the existing config directory. Instead only specific configuration values will be copied.

It is recommended to backup the configuration file within the jadu installation directory before making changes to it.

7a. system.xml

Copy the configuration values from the backed up config/system.xml file into the config/system.xml file of the jadu installation.

secure_key
des_encryption_mssql_cert_pass

7b. constants.xml

Copy the configuration values from the backed up config/constants.xml file into the config/constants.xml file of the jadu installation.

csrf_token_salt
hash_salt
encryption_key

7c. mail.xml

If your original server has a custom mail setup, replace the config/mail.xml file in the jadu installation directory with the one from the source server.

7d. datastore.xml

If you’ve setup non file based caching for the site, update config/datastore.xml with the values from the backup (if applicable). If you have setup non file based caching you will need to update cache_data_store in system.xml to the correct cache type.

7e. ckeditor.xml

Copy the entire file from the backup up config/ckeditor.xml to the jadu config directory config/.

7f. xfp/constants.xml

Copy the entire file from the backup up config/xfp/constants.xml and replace it in the jadu installation directory config/xfp/.

7g. bundles.xml

Copy any <items> from the backup file config/bundles.xml and add them to the file in the jadu installation directory config/. It is not recommended to copy and replace the existing file, instead you should only add the missing entries.

8. Clear Cache

Delete all the contents under the /path/to/jadu/var/cache directory.

9. Patch to latest Jadu

Finally patch to the latest Jadu version. This will update your site to the version of Jadu that supports the new stack (minimum version CMS 20.0.0 and XFP 8.0.0).

If you have Jadu XFP you will need to ensure forms are offline before patching. This needs to be done directly in the database. Open up SQL Management Studio and run the SQL statement

UPDATE JaduXFormsConfiguration SET value = 'false' WHERE name = 'forms_online';

Follow the usual patch process to deploy the patch.

10. Update DNS entries

The site is now ready to test. As the site has been migrated from the source site, update your hosts file to the IP address of the new server and test the site using the original domain.

Additional Nodes

For each additional web node repeat steps 5, 7, 8 and 9 on each web node.

PHP 7.4 Upgrade Guidance Note

This document provides high-level guidance to customers that undertake their own hosting and management of Jadu software running on a LAMP (Linux, Apache, MySQL, PHP) server software stack and wish to undertake an upgrade to PHP 7.4, MariaDB 10.5.

Overall approach

In order to upgrade PHP to version 7.4 the server must be running Centos 7. If you require assistance with upgrading to CentOS 7 from CentOS 6, please contact us first.

The upgrade will be in-place, and will require some amount of service downtime.

The upgrade process will first remove the old packages from the system, before installing the new ones from a repository. Configuration changes are made and the services are started.

You must take a full backup of the system before actioning these changes, and be prepared to restore if necessary.

The shell commands in this guide assume the use of the Bash shell as root.

Note 1: This document assumes you are using the IUS yum repository for PHP packages, hence PHP 7.2 packages will reference package names php72u-... etc. If this is not the case, please adjust the instructions to suit your environment.

Note 2: At the time this document was created (July 2021) Jadu software does not support PHP versions above 7.4, MariaDB versions above 10.5 or CentOS versions above 7.

1. Upgrade PHP

Step 1. Stop Apache and PHP-FPM

systemctl stop httpd php-fpm

Step 2. Obtain and verify a list of installed PHP 7.2 packages

yum list installed 'php72u-*' 2> /dev/null | awk '/php72u/ { print $1 }' | tee ~/php72-modules.txt

Step 3. Remove PHP 7.2 components.

yum remove $(< ~/php72-modules.txt)

Step 4. Install PHP 7.4 components.

yum install $(sed 's/php72u/php74/g' ~/php72-modules.txt) php74-pecl-zip

2. Upgrade MariaDB

Step 1. Stop MariaDB

systemctl stop mariadb

Step 2. Backup old MariaDB configuration

mkdir ~/mysql_backup && cp -R /etc/my.cnf /etc/my.cnf.d ~/mysql_backup

Step 3. Remove existing MariaDB packages

yum remove MariaDB-{client,common,compat,server}

Step 4. Install the MariaDB 10.5 repository, following the instructions on the MariaDB website

Step 5. Install MariaDB 10.5 packages

yum install MariaDB-{client,common,compat,server}

Step 6. Restore old configuration

cp -R ~/mysql_backup/* /etc/

Step 7. Add performance-enhancing configuration. Place the following pastebin content in /etc/my.cnf.d/jadu-performance.conf.

Step 8. Re-install exim and restore exim config

yum install exim -y && cp /etc/exim/exim.conf.rpmsave /etc/exim/exim.conf

Step 9. Set all services to start on boot

systemctl enable exim php-fpm httpd mariadb

3. Final tasks

Step 1. Start LAMP services:

systemctl start httpd mariadb php-fpm

Step 2. Run mysql_upgrade:

mysql_upgrade

Step 3. Verify successful upgrade:

php -v
mysql -V

Non-backwards compatible changes​

Database schema changes​

File changes​

Other changes​

Database schema changes​

File changes​

Directory permission changes when using 2021 Installer​

Testing Compatibility PHP 7.4​

Install PHP CodeSniffer​

Checkout code from repository (if using)​

Run the PHP CodeSniffer​

Analysing the results​

Windows Server 2019 Upgrade Guidance Note​

Overall Approach​

1. Setup new servers​

2. Backup content from old Windows Server​

2a. Backup databases​

2b. Backup directories​

3. Copy content to new server​

4. Update Database​

4a. Take the jadudb database offline.​

4b. Restore jadudb database from the backup.​

4c. Restore Galaxies Site databases.​

5. Update File System Content​

6. Update database permissions​

6a. Add database users​

6b. Remove imported database users​

6c. Update permissions on Certificates and Keys​

7. Update configuration​

7a. system.xml​

7b. constants.xml​

7c. mail.xml​

7d. datastore.xml​

7e. ckeditor.xml​

7f. xfp/constants.xml​

7g. bundles.xml​

8. Clear Cache​

9. Patch to latest Jadu​

10. Update DNS entries​

Additional Nodes​

PHP 7.4 Upgrade Guidance Note​

Overall approach​

1. Upgrade PHP​

2. Upgrade MariaDB​

3. Final tasks​

Non-backwards compatible changes

Database schema changes

File changes

Other changes

Database schema changes

File changes

Directory permission changes when using 2021 Installer

Testing Compatibility PHP 7.4

Install PHP CodeSniffer

Checkout code from repository (if using)

Run the PHP CodeSniffer

Analysing the results

Windows Server 2019 Upgrade Guidance Note

Overall Approach

1. Setup new servers

2. Backup content from old Windows Server

2a. Backup databases

2b. Backup directories

3. Copy content to new server

4. Update Database

4a. Take the jadudb database offline.

4b. Restore jadudb database from the backup.

4c. Restore Galaxies Site databases.

5. Update File System Content

6. Update database permissions

6a. Add database users

6b. Remove imported database users

6c. Update permissions on Certificates and Keys

7. Update configuration

7a. system.xml

7b. constants.xml

7c. mail.xml

7d. datastore.xml

7e. ckeditor.xml

7f. xfp/constants.xml

7g. bundles.xml

8. Clear Cache

9. Patch to latest Jadu

10. Update DNS entries

Additional Nodes

PHP 7.4 Upgrade Guidance Note

Overall approach

1. Upgrade PHP

2. Upgrade MariaDB

3. Final tasks