Upgrading to ME 1.20

Upgrade Instructions

Important Upgrade Notes

• Elentra ME 1.20+ requires PHP 7.3 or higher.

• Elentra ME 1.19+ requires a new deployment strategy. Please do not proceed with deployments using the traditional Capistrano deployment recipe. See Part 4: Updating Deployment Strategy for information on how to upgrade to Deployer.

• You should ensure that Deployer is able to restart supervisor during the deployment process, which may require additional server configuration. See the Installing Supervisor section for more information.

• ElentraAPI is now on Version 5. If you have a branded API, please ensure to upgrade your API to version 5.

• app.json has been moved, please read this section and implement the change after you upgrade

Part 1: Source Code Update

1. From within Sourcetree on your developer workstation, open your existing local Elentra ME Branded Edition (i.e., uni-elentra-1x-me) repository.

2. If you do not currently have a consortium Git remote that points to the Consortium Edition elentra-1x-me repository, then ensure that you add one:

   git remote add consortium [e-mail]:ElentraProject/elentra-1x-me.git

3. 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.

4. Checkout your Branded Edition staging branch (e.g., uni/staging) and create a new branch based on this branch (e.g., uni/staging-v118) 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.

5. Within the "Remotes" section in Sourcetree sidebar, expand the consortium remote, then right click on release/1.20 and click Pull consortium/release/1.20 into uni/staging. 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 the composer.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.

6. Once the merge conflicts have been resolved, commit the merge to your uni/staging branch and continue to Part 2 of the instructions.

We would recommend against pushing your changes to your origin remote at this point. Wait until Part 2 has been completed and you have finished some initial local testing.

Updating a Branded Edition Elentra API

If your insitution does not have/use a Branded Edition Elentra API, then you can 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.

1. To update your Branded Edition Elentra API, first clone or checkout the master branch of your Branded Edition Elentra API to your local environment using Sourcetree.

2. 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.

3. Within the "Remotes" section in Sourcetree sidebar, expand the consortium remote, then right click on master and click Pull consortium/master into uni/master. There may be merge conflicts that must be resolved if customizations made to your Branded Edition Elentra API.

4. Resolve any merge conflicts and commit the changes to the master branch of your Branded Edition Elentra API. Push these changes to your origin remote.

5. 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 v5.0.0 and the composer.json provided with Elentra ME 1.20 specifies that the major version of API version must be ~5.0. Create a new tag where the current date follows the patch version: 5.0.0.20210331. More information about tagging API releases can be found here.

6. Finally, ensure that within your new Deployer deployment recipe (deploy.php) that you set theenabled_branded_api option to true 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:

1. The stock settings.inc.php file with each environmental settings file in use.

2. The www-root/templates/default template directory with each Branded Edition customized template within the www-root/templates directory.

Failure to accurately compare and update all environmental settings files and customized templates will 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.

1. Using a tool like Araxis Merge or Meld, compare www-root/core/config/settings.inc.php with each environmental settings file in the www-root/core/config directory (e.g., settings-staging.inc.php, settings-production.inc.php). When you compare the Consortium Edition settings.inc.php file with your Branded Edition files, you are looking to add additional settings that have been added to the stock settings.inc.php file and remove any settings that have been removed from the stock settings.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 your uni/staging branch.

2. Using a tool like Araxis Merge or Meld, compare the www-root/templates/default directory with each Branded Edition customized template in the www-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 your header.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 your uni/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.

1. Log into your local elentra-developer Docker container, and change to your uni-elentra-1x-me directory:

   docker exec -it elentra-developer bash
   cd /var/www/vhosts/uni-elentra-1x-me

2. Ensure that the latest Composer dependencies installed:

   composer install

3. Ensure that the database migrations are completed:

   php elentra migrate --up

4. 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: Updating Deployment Strategy

Elentra ME 1.19+ requires a deployment recipe transition from Capistrano v2.15 to Deployer v6.8.0 in order to support the new requirement of a local build step for Elentra JS 2.

The following transition instructions are to be used as reference-only, as there may be unique circumstances within your existing Capistrano recipe to be considered.

While these instructions may seem complex, the transition is relatively straightforward. If you open both recipe files (Capistrano's deploy.rb and Deployer's deploy.php) you will see the same/similar variables, structure, and patterns.

The full Elentra Deployment Tool documentation is available from within the Elentra Deployment documentation section. It may be helpful to read that in addition to this.

Part 4 / Step 1: Copy Deployer template files into your Branded Edition repository.

Download the raw .deployignore and deploy.php files from the Elentra Developer GitHub Repository and place them in your ~/Sites/uni-elentra-1x-me/deployment directory alongside the existing Capistrano Capfile and config/deploy.rb files in the uni/staging branch.

Part 4 / Step 2: Update the Deployer recipe template with actual values.

Open both the Capistrano ("Cap") deployment/config/deploy.rb and the Deployer ("Dep") deployment/deploy.php deployment recipes in your editor or IDE. 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.

Capistrano (deploy.rb)	Deployer (deploy.php)	Description
application	application	Application Name (e.g., uni-elentra-1x-me)
	packagist_token	Institutional Packagist.com Composer token
repository	repository	Branded Edition Elentra ME Git repository location
	branch	The default deployment branch (e.g., master) within your Branded Edition Elentra ME Git repository. This value is always overridden by the host configuration section (if present), so it not overly important.
	repository_ejs	Default recommended. This can be left as-is unless you have a Branded Edition Elentra JS Git repository.
	branch_ejs	Default recommended. This can be left as-in unless you have a Branded Edition Elentra JS Git repository. This value is always overridden by the host configuration section (if present), so it not overly important.
	enable_branded_api	Default value is false. If you have a Branded Edition Elentra API with your implementation of Elentra then please set this to true.

Once you have set all of the variable names correctly in comparison with the Capistrano recipe, 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 Capistrano (deploy.rb) Recipe

# Elentra ME
task :staging do
  server "elentra-staging.med.university.edu", :app, :web, :db, :primary => true

  set :user, "staging"

  set :branch, "uni/staging"
  set :environment, "staging"
  set :deploy_to, "/var/www/vhosts/elentra-staging.med.university.edu"
end
task :production do
  server "elentra01.med.university.edu", :app, :web, :primary => true
  server "elentra02.med.university.edu", :app, :web

  set :user, "production"

  set :branch, "uni/production"
  set :environment, "production"
  set :deploy_to, "/var/www/vhosts/elentra.med.university.edu"
end

Example Deployer (deploy.php) Recipe

# Elentra ME

// Staging Server
host('elentra-staging.med.university.edu')
    ->stage('staging')
    ->user('staging')
    ->set('branch', 'uni/staging')
    ->set('branch_ejs', 'develop')
    ->set('deploy_path', '/var/www/vhosts/elentra-staging.med.university.edu')
    ->roles('app')
    ->forwardAgent();

// Production Server
host('elentra01.med.university.edu', 'elentra02.med.university.edu')
    ->stage('production')
    ->user('production')
    ->set('branch', 'uni/production')
    ->set('branch_ejs', 'master')
    ->set('deploy_path', '/var/www/vhosts/elentra.med.university.edu')
    ->roles('app')
    ->forwardAgent();

Part 4 / Step 3: Review the deployment command crosswalk.

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 should be fully backwards compatible with your previous Capistrano recipe.

Capistrano	Deployer
cap staging deploy	dep deploy staging
cap production deploy	dep deploy production
cap staging deploy:rollback	dep rollback staging

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.

1. Log into your local elentra-developer Docker container, and change to your deployment directory:

   docker exec -it elentra-developer bash
   cd /var/www/vhosts/uni-elentra-1x-me/deployment

2. Deploy changes to your staging server using the new Deployer deployment recipe:

   dep deploy staging

3. 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 very 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.

1. From within Sourcetree on your developer workstation, open your existing local Elentra ME Branded Edition (i.e., uni-elentra-1x-me) repository.

2. Checkout your uni/production branch.

3. 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 your uni/production branch.

4. Push the commits in the uni/production branch to your origin remote. Log into your local elentra-developer Docker container, and change to your deployment directory:

   docker exec -it elentra-developer bash
   cd /var/www/vhosts/uni-elentra-1x-me/deployment

5. Deploy changes to your production server using the new Deployer deployment recipe:

   dep deploy production

6. Providing the deployment was successful, you should now be able to visit https://elentra.med.university.edu in your web browser and enjoy the fact that you are now running the latest version of Elentra ME.

Additional Changes

app.json has been moved

As of March 22nd, 2021, the ElentraAPI has been upgraded to Laravel 6, which changes the location of the app.json file. If you pull from the release branch, or if you're upgrading for the first time, please run these commands on your servers.

rm /var/www/vhosts/host.name.edu/storage/app/modules/app.json
ln -s /var/www/vhosts/host.name.edu/current/www-root/core/storage/app/modules/app.json /var/www/vhosts/host.name.edu/storage/app/modules/app.json