Upgrading to Windows Server 2019
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.
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 the Installation section.
Ensure you can log into the Control Centre 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.
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_keydes_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_salthash_saltencryption_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/.
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.