Upgrading to ME 1.26
Elentra ME 1.26 was released on April 4th, 2023.
Release 1.27 introduced breaking changes to EJS 2. If you are using a version of Elentra that is 1.26.0 or less, you need to update deploy.php to ensure "branch_ejs" is pointing to "v2.6.0"
Important Upgrade Notes
Elentra ME now uses Node Package Manager (npm) to manage front-end javascript dependencies such as jQuery and bootstrap. You will need to add a deployment step to install npm packages and run the vite build.
All exceptions are now being logged in error_log.txt
, by way of a global exception handler, along with an Error ID shown to the user.
Please review the Important Changes section before proceeding.
Elentra ME 1.26 requires PHP 8, and uses Laravel 9.
This is important if you are upgrading from a release that does not require PHP 8 or Laravel 9, for example 1.23.
Part 1: Source Code Update
From within Sourcetree on your developer workstation, open your existing local Elentra ME Branded Edition (i.e.,
uni-elentra-1x-me
) repository.If you do not currently have a
consortium
Git remote that points to the Consortium Editionelentra-1x-me
repository, then ensure that you add one:Click the "Fetch" button (ensuring that "Fetch from all remotes" and "Prune tracking branches no longer present on remote(s)" options are checked) or type
git fetch consortium
.Checkout your Branded Edition staging branch (e.g.,
uni/staging
) and create a new branch based on this branch (e.g.,uni/staging-pre-1240
) just for easy restore purposes in case it's needed. Once that branch has been created, checkout the original Branded Edition staging branch (e.g.,uni/staging
) and continue.Within the "Remotes" section in Sourcetree sidebar, expand the
consortium
remote, then right click onrelease/1.26
and clickPull consortium/release/1.26 into uni/staging
. To be safe, you can pull the latest stable release tag (e.g.v1.26.2
) instead. At this point, you may be asked to resolve any merge conflicts that have been created by making modifications to your Branded Edition that conflict with changes that have been made to the Consortium Edition. Depending on your level of conflict, this could be as simple as a minor modification to thecomposer.lock
file or something much more complex. If you require assistance, please book an appointment with the Elentra Consortium Core Team, or chat with us on Slack in the #developers channel and we will provide you with guidance or assistance on moving forward. Generally speaking, we always recommend that Consortium Participants follow the Contribution best practices defined in our documentation, which may help reduce the number of conflicts that you encounter.Once the merge conflicts have been resolved, commit the merge to your
uni/staging
branch and continue to Part 2 of the instructions.
We recommend against pushing your changes to your origin
remote at this point. Please wait until Part 2 has been completed and you have finished some initial testing on your local developer environment.
Release branches (e.g. release/1.26
) usually only get bug fixes and have low potential risk, but issues may not be identified until our integration testing before the next release. Therefore, release branches are not completely stable. Release tags (e.g. v1.26.0
), on the other hand, are NEVER actively worked on and are the official minor release for a given major release, because tags are only created from the release/1.x branches AFTER our integration testing has passed.
Updating a Branded Edition Elentra API
If your institution does not have a Branded Edition Elentra API, skip this section entirely. These instructions are only applicable to installations of Elentra that have a Branded Edition Elentra API. Not sure? Please contact the Elentra Consortium Core Team for assistance.
To update your Branded Edition Elentra API, first clone or checkout the compatible version of your Branded Edition Elentra API to your local environment using a git tool like Sourcetree. To find the required version, please consult the Compatibility Matrix.
Click the "Fetch" button (ensuring that "Fetch from all remotes" and "Prune tracking branches no longer present on remote(s)" options are checked) or type
git fetch consortium
.Within the "Remotes" section in Sourcetree sidebar, expand the
consortium
remote, then right click on the identified branch from step 1 (i.e. compatible version listed in Compatibility Matrix) and clickPull consortium/<branch> into <Deployed Branch>
. There may be merge conflicts that must be resolved if customizations made to your Branded Edition Elentra API.Resolve any merge conflicts and commit the changes to the
master
branch of your Branded Edition Elentra API. Push these changes to yourorigin
remote.Using Sourcetree, create a new tag that follows semantic versioning. For example at the time of writing, the latest tagged release of the api is
v8.0.0
and thecomposer.json
provided with Elentra ME 1.26 specifies that the major version of API version must be~8.0
. Create a new tag where the current date follows the patch version:8.0.1.20230406
. More information about tagging API releases can be found here.Finally, ensure that within your new Deployer deployment recipe (
deploy.php
) to set theenabled_branded_api
option totrue
and the deployment script will take care of the rest during deployment.
Part 2: Settings and Branding Update
During every major Elentra ME version upgrade, you are required to compare:
The stock settings.inc.php file with each environmental settings file in use.
The www-root/templates/default template directory with each Branded Edition customized template within the www-root/templates directory.
Failure to compare and update all environmental settings files and customized templates could result in a non-functional or semi-functional installation of Elentra ME. If you have questions or require assistance, please contact the Elentra Consortium Core Team.
Using a tool like Araxis Merge or Meld, compare
www-root/core/config/settings.inc.php
with each environmental settings file in thewww-root/core/config
directory (e.g.,settings-staging.inc.php
,settings-production.inc.php
). When you compare the Consortium Editionsettings.inc.php
file with your Branded Edition files, you are looking to add additional settings that have been added to the stocksettings.inc.php
file and remove any settings that have been removed from the stocksettings.inc.php
file. In most cases, your Branded Edition settings files should have the same lines (albeit potentially different settings values) as the Consortium Edition. Once you have compared your settings files, commit the changes to youruni/staging
branch.Using a tool like Araxis Merge or Meld, compare the
www-root/templates/default
directory with each Branded Edition customized template in thewww-root/templates
directory (e.g.,www-root/templates/uni
). In most cases, you will want to add missing files, update your language files, examine each modification to the CSS files, and add any modifications to yourheader.tpl.php
files. This process can take some time depending on the level of change in your implementation, and should be repeated for each template you have created. Once you have compared your templates, commit the changes to youruni/staging
branch.
Part 3: Testing Locally
Now that you have upgraded your source code and updated your settings and templates. You should begin reviewing and testing the upgrade on your developer workstation. Before testing can begin we need to do a few things.
Log into your local
elentra-developer
Docker container, and change to youruni-elentra-1x-me
directory:Ensure that the latest Composer dependencies installed:
Ensure that the database migrations are completed:
Providing these steps were successful, you should now be able to visit https://uni-elentra-1x-me.localhost in your web browser and being your local upgrade review.
At this point, providing you're satisfied with your local testing, we would recommend that you push your changes to your origin
remote.
Part 4: Configuring Deployer
Elentra ME 1.26 requires Deployer v6.8.0 in order to support the new requirement of a local build step for Elentra JS 2. If you already have Deployer configured, you can skip this step.
The full Elentra Deployment Tool documentation is available from within the Elentra Deployment documentation section.
The following transition instructions are to be used as reference-only, as there may be unique circumstances within your existing deployment recipe to be considered.
Step 1: Copy Deployer template files into your Branded Edition repository
Copy the .deployignore
and deploy.php
files from the Elentra Developer GitHub Repository and place them in your ~/Sites/uni-elentra-1x-me/deployment
directory
Step 2: Update the values in the Deployer recipe template
Open the Deployer deployment/deploy.php
deployment recipes in your editor. There are a few variables at the top of deploy.php
that need to be set. The following table describes variable names that must set.
Once you have configured all of the variables correctly, the next step is to translate the hosts configuration. The following section illustrates a single staging server and multiple production server transition.
For more documentation related to host configuration options, please see the Deployer Hosts documentation, which is quite extensive.
Example Deployer (deploy.php) Recipe Host configuration
Step 3: Review Deployment Commands
The typical deployment commands used by institutions are referenced below, but please see the Elentra Deployment documentation for a full list of all commands available.
The Deployer deployment strategy transition should require no Apache configuration changes and was designed to be fully backwards compatible with older Capistrano recipes.
Part 5: Testing on Staging
Providing that you have pushed the changes to your uni/staging
branch to your origin
remote, you can now deploy the upgrade to your staging environment from within your Docker container.
Log into your local
elentra-developer
Docker container, and navigate to yourdeployment
directory:Deploy changes to your staging server using the new Deployer deployment recipe:
Providing the deployment was successful, you should now be able to visit https://elentra-staging.med.university.edu in your web browser to begin a thorough review of your upgraded Branded Edition implementation of Elentra ME.
For the most accurate review possible, we would recommend that you have a recent version of your production databases installed and scrubbed loaded on your staging database server. This is typically achieved using the scrub.sh
shell script included with the Elentra Platform.
Part 6: Deploy to Production
Providing that you have thoroughly tested your upgraded Branded Edition implementation of Elentra ME on within your staging environment, it is safe to proceed with a production upgrade.
From within Sourcetree on your developer workstation, open your existing local Elentra ME Branded Edition (i.e.,
uni-elentra-1x-me
) repository.Checkout your
uni/production
branch.Right click on your
uni/staging
branch and click "Merge uni/staging into uni/production". This will merge all of the commits that have gone into creating the upgrade, into youruni/production
branch.Push the commits in the
uni/production
branch to yourorigin
remote. Log into your localelentra-developer
Docker container, and change to yourdeployment
directory:Deploy changes to your production server using the new Deployer deployment recipe:
Providing the deployment was successful, you should now be able to visit https://elentra.med.university.edu in your web browser and verify that you are now running the latest version of Elentra ME.
Important Changes
This release contains significant changes, and you will need to regression test all of your customisations in case these updates break them.
Smarty update
The SMARTY template library was upgraded from version 3.1.46 to version 4.3.1
JavaScript library updates
jQuery has been updated from version 1.12.3 to version 3.7.1
Bootstrap has been updated from version 2.3.1 to version 3.4.1
The following libraries have been consolidated, resulting in the removal of non-minified versions, e.g. deleting
vue.js
but keepingvue.min.js
. If your institution is relying on these libraries, you may need to update your customizations to point to the minified version.www-root/javascript/vue/vue.js
www-root/javascript/jquery/moment.js
www-root/javascript/Chart/Chart.js
www-root/javascript/Chart/Chart.bundle.js
www-root/javascript/chart_js/Chart.min.js
www-root/javascript/Chart/Chart.bundle.min.js -> Chart.min.js
www-root/javascript/axios/axios.js
www-root/javascript/jquery/jquery-1.10.2.min.js
www-root/javascript/jquery/jquery-1.12.3.min.js
www-root/javascript/jquery/jquery-3.1.1.min.js
www-root/javascript/jquery/jquery-ui.min.js
www-root/javascript/jquery/jquery.dataTables.min-1.10.1.js
www-root/javascript/jquery/jquery.jswipe.js
www-root/javascript/jquery/jquery.loadTemplate.js
www-root/javascript/jquery/jquery.loadTemplate.min.js
www-root/javascript/jquery/jquery.min.js
www-root/javascript/jquery/jquery.modal.js
www-root/javascript/jquery/jquery.moment.min.js
www-root/javascript/jquery/jquery.qtip.js
www-root/javascript/jquery/jquery.touchSwipe.js
www-root/javascript/jquery/jquery.validate.min.js
*Javascript package management
NPM and Vite are now used to manage javascript dependencies such as jQuery and Bootstrap. Add the following lines to your
deploy.php
aftertask('deploy:vendors')
Node version v14.18 is required for this step to work.
Error handling
ALL exceptions, their full stack trace, and a unique Error ID also shown to the user, are now being logged in error_log.txt
. This means that users will now see an error message like the one below, whenever any uncaught exception is thrown in elentra-1x-me PHP code.
In order to diagnose the issue, simply copy the Error ID (in this case "2023-09-13T17:02:40-E21a", and search for this string in the storage/logs/error_log.txt
file on the server. You should find a log message similar to the following:
Last updated