# Upgrading to ME 1.18 ## Upgrade Instructions {% hint style="danger" %} * Please note that Elentra ME v1.18.1+ requires PHP 7.3 or higher. * 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](https://docs.elentra.org/technical/upgrade-guides/upgrading-to-me-1.18#app-json-has-been-moved) and implement the change after you upgrade {% endhint %} ### 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 an `consortium` Git remote that points to the Consortium Edition `elentra-1x-me` repository, then ensure that you add one: ``` git remote add consortium git@github.com: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-v117`) 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.18` and click `Pull consortium/release/1.18 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 some guidance on moving forward. As a point of note, we always recommend that Consortium Participants follow the [Contribution](https://docs.elentra.org/technical/developers/contributions) best practices defined in our documentation, which may help reduce the number of conflicts that you encounter.
6. Once the conflicts have been resolved, commit the merge to your `uni/staging` branch and continue to Part 2 of the instructions. {% hint style="danger" %} 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. {% endhint %} #### Updating a Branded API {% hint style="info" %} Branded API changes should be base off of the upstream `master` branch. {% endhint %} 1. To update your branded Elentra API, first clone or checkout the master branch of your Branded 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 API.
4. Resolve any merge conflicts and commit the changes to the `master` branch of your Branded API. Push any changes to your Branded API remote.
5. Using Sourcetree or your project service of choice, create a new tag that follows semantic versioning. For example at the time of writing, the latest tagged release of the api is `v4.0.2` and the `composer.json` provided with Elentra ME 1.18 specifies that the major version of API version must be `~4.0`. Create a new tag where the current date follows the patch version: `4.0.2.20200512`. [More information about tagging API releases can be found here](https://docs.elentra.org/technical/administrators/application-server/branded-api-setup#tagging-releases).
6. In your Branded Edition of Elentra ME, run `composer update elentrapackages/elentra-1x-api` and commit the changes to the `composer.lock` file. ### Part 2: Configuration and Branding Update 1. 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.
2. 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. 1. Log into your local `elentra-developer` Docker container, and change to your `uni-elentra-1x-me` directory: ```bash docker exec -it elentra-developer bash cd /var/www/vhosts/uni-elentra-1x-me ``` 2. Ensure that the latest Composer dependencies installed: ```bash composer install ``` 3. Ensure that the database migrations are completed: ```bash php elentra migrate --up ``` 4. Providing these steps were successful, you should now be able to visit in your web browser and being your review. {% hint style="success" %} At this point, providing you're satisfied with your local testing, we would recommend that you push your changes to your `origin` remote. {% endhint %} ### 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. 1. Log into your local `elentra-developer` Docker container, and change to your `deployment` directory: ```bash docker exec -it elentra-developer bash cd /var/www/vhosts/uni-elentra-1x-me/deployment ``` 2. Deploy changes to your staging server: ```bash cap staging deploy ``` 3. 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. {% hint style="info" %} 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. {% endhint %} ### 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. 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: ```bash docker exec -it elentra-developer bash cd /var/www/vhosts/uni-elentra-1x-me/deployment ``` 5. Deploy changes to your production server: ```bash cap production deploy ``` 6. 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. ## Additional Changes ### **Quizzes Module** The quizzes module has been disabled by default. We now recommend using the Exams module instead. You can however re-enable the Quizzes module in `settings.inc.php` by re-adding the quizzes declaration in the `$MODULES` array, like so: `$MODULES["quizzes"] = array("title" => "Manage Quizzes", "resource" => "quiz", "permission" => "update");` ### Absence Management Module This new module allows users to upload files, which are stored in `www-root/core/storage/app/absence-files`. You will need to create the folder in your staging and production, otherwise file uploads will fail. ### Profile Menu Item Order Version 1.18 includes a new setting `user_menu_ordering` which allows you to order the menu items in the User Profile Dropdown in the Navbar. The setting comes loaded with a default, however you may edit those values as you see fit. ### 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 ``` {% hint style="info" %} [ME-3273](https://elentra.atlassian.net/browse/ME-3273) adds a new menu item "My Learners" for faculty and staff users. A migration will automatically insert this menu item to the `user_menu_ordering` setting as the first item. {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.elentra.org/technical/upgrade-guides/upgrading-to-me-1.18.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.