Curator Best Practices: Scripted Deployment-Based Upgrades

Matthew Orr
Curator Engineer
August 26, 2022

Disclaimer

The topic discussed here is not covered by Curator support and is not recommended as it is difficult to predict all the ways this may cause problems as the platform evolves. This is only a guide provided as an attempt to make your life easier if you need to use a scripted deployment procedure for Curator due to internal IT policies. By taking the approach discussed below, you are assuming the burden of setting it up to work in your environment, maintaining it as needed and fixing issues as they arise. You’ve been warned. Good luck!

What Are We Talking About Here?

The Curator team continues to strive toward making the upgrade process as smooth and reliable as possible. We’ve created one-click upgrade button, manual upgrade options for air-gapped installations and we continue to adjust as new flaws are found. With that said, sometimes IT policies require special upgrade procedures that must bypass the standard upgrade options. While these custom procedures aren’t supported by the Curator team, we can make recommendations on the most reliable way to carry out those procedures so they mesh as much as possible with Curator’s expectations.

One pattern we’ve seen a few different customers implement automates the deployment of a new web server with a new installation of Curator on top by using a scripting framework – think things like Docker, Cloud Formation, Ansible and similar tools. While this approach introduces complications around the upgrade process, there are some best practices that can make it more successful. If you’re looking to implement one of these scripted deployment-based approaches, this will outline the gist of how you’ll want to go about it and identify some gotchas you may want to handle.

Redeployment Process

It’s one thing to script the creation of a new Curator portal; it’s a totally different beast to script the fresh deployment of a cloned Curator portal. The general flow you’ll want to take is:

1. Deploy the server (operating system, memory, storage, cup holders, vanity plates, etc.)
2. Install Curator and its prerequisites (our installers are a great starting point)
3. Take a full backup of the existing Curator portal (using the built-in full backup functionality includes both the contents of the web root folder and the database on standard installs)
4. If needed, modify the database connection details of the full backup to match the new portal details (process documented below)
5. Restore that full backup on to the new Curator portal
6. Upgrade the Curator portal (use the UI buttons, CLI artisan command or API to trigger the upgrade)

Gotchas

Custom Setup

While redeploying a Curator portal, you may need to specify the database connection details, persistent storage location, license key or other advanced configuration. The Linux installer includes various arguments to set these during the install. See the section on “Custom Setup” at this post for more details.

2-Part Process

Curators normal upgrade procedure is a two-part process: Upgrade the code and modify the database as needed. Without both steps in whatever process you use, Curator will behave more like a drunken robot spewing vile error messages at you. The following CLI artisan command from Curator’s web root directory should handle the database modifications if you’ve got the code updates covered.

Linux (Redhat-like installations):

sudo -u apache php artisan portal:migrate

Linux (Ubuntu-like installations):

sudo -u www-data php artisan portal:migrate

Windows Server:

php.exe artisan portal:migrate

Configuration

One area of a Curator installation that isn’t touched by the normal upgrade procedure but is overwritten by a full backup restoration is the /config/ directory. I know what you’re thinking based on the name of it, but this directory actually houses some configuration settings for Curator. What’s that? Oh, that is what you were thinking? Well, color me impressed.

Anyhoo, the two most important ones for this topic are the database connection details and the encryption key used for encrypting sensitive data at rest in Curator’s database. The connection details are set during installation and changing them after the fact is an involved process. The encryption key is auto-generated during the installation process. If you’re restoring to a system that uses different database connection details, you’ll need to modify the backup to include those details prior to restoration (process documented below). However, if you’re restoring the previously encrypted data from a different installation, you’ll need to retain the encryption key that was used to encrypt the data (set in /config/app.php).

Handling Temporary URL Changes

Usually, the new deployment will happen before the previous one is decommissioned. This means that the new deployment is likely using a temporary URL. Curator includes a few different areas where the URL matters:

• There’s a Forced Curator Domain setting under Backend > Settings > Curator > Portal Settings > General tab > Security section that can restrict access to the frontend.
• If you’re using SAML, Oauth or Power BI, the redirect URL used by those systems likely doesn’t know about the new temporary URL so they will likely send you back to the previous installation.

Missing Cron/Scheduled Task

Curator installers add a cron/scheduled task to run its process queue once per minute. Be sure whatever redeployment procedure you use sets up this cron (Linux) or scheduled task (Windows) to run as the web server’s user (apache, www-data or SYSTEM) and, specifically with Windows, to run every minute whether anyone is logged into the server or not. It’s not always immediately apparent when this is missed, but it will cause issues over time.

Modifying Database Connection in a Full Backup

Curator stores the database connection details in /config/database.php. Full backups created by Curator are structured as follows:

• A dump of Curator’s database (.sql file)
• Copy of Curator’s web root directory (.zip file)

The zip archive of the web root within a full backup also contains those same connection details. If the database connection differs from the system the backup originated from to the system being restored over, you'll need to perform these steps prior to restoring:

• Unzip the full backup zip archive to a temporary location (i.e. not inside either Curator portal’s actual web root).
• Unzip the web root zip archive.
• Modify the config/database.php file as needed in the extracted web root folder to match the connection details of the database you'll be restoring over.
• Re-zip the extracted web root folder (use the same file name for the resulting zip archive).
• If the MySQL/MariaDB database name (not to be confused with host or username) differs, rename that part of the database dump SQL script. Be sure to retain the datestamp and file extension portions of the file name.
• Re-zip the web root zip archive (not to be confused with the extracted web root directory) and the database dump SQL script as the full backup (use the same file name for the resulting zip archive).
• Transfer the updated full backup zip archive to the system you wish to restore over and place it in the directory where full backups are stored (default is /storage/temp/).