Elentra Platform Technical Documentation

Upgrading to ME 1.15

Upgrade instructions for upgrading from Elentra ME 1.13 or 1.14 to version 1.15.

Last updated 5 years ago

Upgrading to ME 1.15

Upgrade instructions for upgrading from Elentra ME 1.13 or 1.14 to version 1.15.

This upgrade guide assumes you are presently running Elentra ME 1.13 or 1.14. If you are running Entrada ME 1.12 or earlier please consult with the Elentra Consortium Core Team prior to upgrading and they will provide personalized assistance.

Upgrade Instructions

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 an upstream Git remote that points to your up-to-date Institutional Fork or to the Consortium Edition elentra-1x-me repository, then ensure that you add one:
```
git remote add upstream git@github.com:ElentraProject/elentra-1x-me.git
```
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 upstream.
Checkout your Branded Edition staging branch (e.g., uni/staging) and create a new branch based on this branch (e.g., uni/staging-v113) 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 upstream remote, then right click on release/1.15 and click "Pull upstream/release/1.15 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 and we will provide you with some guidance on moving forward. As a point of note, we always recommend that Consortium Participants follow the best practices defined in our documentation, which may help reduce the number of conflicts that you encounter.
Once the 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 have finished some initial local testing.

Part 2 - Configuration and Branding Update

Using a tool like Araxis Merge, compare www-root/core/config/settings.inc.php with the settings-staging.inc.php and settings-production.inc.php files in the same directory. If you have alternatively named or additional settings files, use those instead. 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.
Using a tool like Araxis Merge, compare the www-root/templates/default directory with your own Branded Edition templates (e.g., www-root/templates/uni). In many cases, you will want to add missing files, update your language files, add any additions to the CSS files, add modifications to your header.tpl.php files, etc. This process can take a bit of time and should be repeated for each additional template that 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 work station. Before testing can begin we need to do a few things.

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
```
Ensure that the latest Composer dependencies installed:
```
composer install
```
Ensure that the database migrations are completed:
```
php elentra migrate --up
```

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 - 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 change to your deployment directory:
```
docker exec -it elentra-developer bash
cd /var/www/vhosts/uni-elentra-1x-me/deployment
```
Deploy changes to your staging server:
```
cap staging deploy
```

For the most accurate review possible, we would recommend that you have a very recent version of your production databases installed and scrubbed on your staging database server. This is typically achieved using the scrub.sh shell script included with the Elentra Platform.

Part 5 - 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 your uni/production branch.
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
```
Deploy changes to your production server:
```
cap production deploy
```

Post-Upgrade Requirements

Once you have completed the source code upgrade to Elentra ME 1.15 and things are running smoothly in production, we need to do a few additional steps.

Add New Cronjobs (for 1.13 to 1.15 upgrades only)

This step is only required if you are upgrading from Elentra ME 1.13 directly to 1.15.

Log into your application server as the production user, edit the crontab by typing crontab -e, and add the following lines, ensuring that you replace ENTRADA_ABSOLUTE with that actual absolute path to your directory (e.g., /var/www/vhosts/elentra.med.university.edu/current/www-root).

*/5 * * * * php ENTRADA_ABSOLUTE/cron/capture-google-calendar-sync.php > /dev/null 2>&1
*/30 * * * * php ENTRADA_ABSOLUTE/cron/publish-curriculum-version.php > /dev/null 2>&1

Installing Supervisor

yum install supervisor
systemctl enable supervisord
systemctl start supervisord

Create a new file in the /etc/supervisor.d directory called elentra.ini, and use the following template snippet as a reference to create your own file.

Please make sure that you have the correct path in command and stdout_logfile, and that user is the correct system account that your existing cron jobs are run as.

[program:elentra]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/vhosts/elentra.med.university.edu/current/www-root/core/library/vendor/elentrapackages/elentra-1x-api/artisan queue:work --queue=high,emails,default,low --env=production
autostart=true
autorestart=true
user=production
numprocs=1
redirect_stderr=true
stdout_logfile=/var/www/vhosts/elentra.med.university.edu/storage/logs/worker.log

Restart Supervisor:
```
systemctl restart supervisord
```

PreviousUpgrading to ME 1.16

Last updated 5 years ago

Upgrade Instructions

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 an upstream Git remote that points to your up-to-date Institutional Fork or to the Consortium Edition elentra-1x-me repository, then ensure that you add one:
```
git remote add upstream git@github.com:ElentraProject/elentra-1x-me.git
```
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 upstream.
Checkout your Branded Edition staging branch (e.g., uni/staging) and create a new branch based on this branch (e.g., uni/staging-v113) 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 upstream remote, then right click on release/1.15 and click "Pull upstream/release/1.15 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 and we will provide you with some guidance on moving forward. As a point of note, we always recommend that Consortium Participants follow the best practices defined in our documentation, which may help reduce the number of conflicts that you encounter.
Once the 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 have finished some initial local testing.

Part 2 - Configuration and Branding Update

Using a tool like Araxis Merge, compare www-root/core/config/settings.inc.php with the settings-staging.inc.php and settings-production.inc.php files in the same directory. If you have alternatively named or additional settings files, use those instead. 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.
Using a tool like Araxis Merge, compare the www-root/templates/default directory with your own Branded Edition templates (e.g., www-root/templates/uni). In many cases, you will want to add missing files, update your language files, add any additions to the CSS files, add modifications to your header.tpl.php files, etc. This process can take a bit of time and should be repeated for each additional template that you have created. Once you have compared your templates, commit the changes to your uni/staging branch.

Part 3 - Testing Locally

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
```
Ensure that the latest Composer dependencies installed:
```
composer install
```
Ensure that the database migrations are completed:
```
php elentra migrate --up
```
Providing these steps were successful, you should now be able to visit in your web browser and being your 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 - 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 change to your deployment directory:
```
docker exec -it elentra-developer bash
cd /var/www/vhosts/uni-elentra-1x-me/deployment
```
Deploy changes to your staging server:
```
cap staging deploy
```
Providing the deployment was successful, you should now be able to visit in your web browser to begin a thorough review of your upgraded Branded Edition implementation of Elentra ME.

Part 5 - 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 your uni/production branch.
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
```
Deploy changes to your production server:
```
cap production deploy
```
Providing the deployment was successful, you should now be able to visit in your web browser and enjoy the fact that you are now running the latest version of Elentra ME.

Post-Upgrade Requirements

Once you have completed the source code upgrade to Elentra ME 1.15 and things are running smoothly in production, we need to do a few additional steps.

Add New Cronjobs (for 1.13 to 1.15 upgrades only)

This step is only required if you are upgrading from Elentra ME 1.13 directly to 1.15.

*/5 * * * * php ENTRADA_ABSOLUTE/cron/capture-google-calendar-sync.php > /dev/null 2>&1
*/30 * * * * php ENTRADA_ABSOLUTE/cron/publish-curriculum-version.php > /dev/null 2>&1

Installing Supervisor

Elentra ME 1.15 requires a new RHEL / CentOS package available in epel, called Supervisor. Supervisor is a process control system used to ensure that are running, in order to process newly queued jobs. To install supervisor, simply run:
```
yum install supervisor
systemctl enable supervisord
systemctl start supervisord
```

Create a new file in the /etc/supervisor.d directory called elentra.ini, and use the following template snippet as a reference to create your own file.

Please make sure that you have the correct path in command and stdout_logfile, and that user is the correct system account that your existing cron jobs are run as.

[program:elentra]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/vhosts/elentra.med.university.edu/current/www-root/core/library/vendor/elentrapackages/elentra-1x-api/artisan queue:work --queue=high,emails,default,low --env=production
autostart=true
autorestart=true
user=production
numprocs=1
redirect_stderr=true
stdout_logfile=/var/www/vhosts/elentra.med.university.edu/storage/logs/worker.log

Restart Supervisor:
```
systemctl restart supervisord
```