Upgrading to ME 1.11

Introduction

This documentation will serve as a help guide for developers seeking to upgrade their institutional forks of Entrada ME to version 1.11. Most Entrada ME upgrades are relatively straightforward; however, there are a few important things to note and consider about version 1.11. This guide can help you avoid and troubleshoot some of common problems.

Entrada API Filesystem Location

There was a relatively significant change to how the new RESTful Entrada API is loaded into the application in this release. This codebase, formerly located in www-root/core/api, is now a separate Git repository available from entrada-1x-api and is loaded into the codebase as a Composer dependency. The new filesystem location is www-root/core/library/vendor/entradapackages/entrada-1x-api, but the API is still accessed via URL at http://entrada-1x-me.localhost/api/v2.

Further documentation on optimal deployment strategies is forthcoming.

Settings File Changes

Please Note: Make sure this value is changed for all of your environments (i.e. settings-staging.inc.php, settings-production.inc.php, etc.).

New Storage Directories

You will notice that there are several new directories added to your $config->entrada_storagedirectory:

/cbme-uploads

Make a note of these new directories because you might have to change how you deploy your code if you have changed the default storage location. The storage location is configured in the www-root/core/config/config.inc.php file. If you're using an external storage directory, you will need to create these directories manually if they do not exist.

Enable Laravel Debug Mode

If you are having problems logging into Entrada ME 1.11 and do not see anything in the api.log file, you can enable debug mode within Laravel, which will force error messages to be displayed.

To enable Laravel debug mode create a new file called .env in www-root/core/library/vendor/entradapackages/entrada-1x-api and add the following line:

APP_DEBUG=true

Once debug mode is enabled, you should be able to see Laravel generated error messages in the browser by visiting ENTRADA_URL/api/v2.

Template Changes

There were several important changes to the default template in Entrada ME 1.11 within the www-root/templates/default directory. You will need to make sure that these changes exist in all of your non-default template folders.

To make the appropriate changes to your template we recommend using a product like Araxis Merge, Beyond Compare, or Meld to compare the www-root/templates/default with your institutional template in the same directory.

CRON Changes

There are 3 new required cronjobs in Entrada ME 1.11, which you should add to your productionusers crontab. To do this you will need to log in via SSH as the production user and type crontab -e:

0 * * * * php ENTRADA_ABSOLUTE/cron/publish-form-blueprints.php > /dev/null 2>&1
*/30 * * * * php ENTRADA_ABSOLUTE/cron/assessment-statistics.php >/dev/null 2>&1
*/10 * * * * php ENTRADA_ABSOLUTE/cron/queue-assessment-notifications.php > /dev/null 2>&1

Common Problems

You did not update the required PHP packages with composer.

Solution: Run composer update

You did not apply the database migrations.

Solution: Run php entrada migrate --up

Apache cannot write to the new directories that were created in your storage directory.

Solution: This is entirely dependant on the existing permissions of your $config->entrada_storagedirectory.

If the $config->entrada_storage is owned by staging or production OS user account:

find www-root/core/storage -type d -exec chmod 0777 {} \;

If the $config->entrada_storage is owned by the OS user account:

find www-root/core/storage -type d -exec chmod 0755 {} \;

Laravel Can't Find bootstrap/cache.

Try clearing the cache using Laravel's artisan command. WARNING This can potentially delete all of the folders in the storage directory and you will need to get them back. Either make a backup of the storage folder and restore it or restore with git.

cd www-root/core/library/vendor/entradapackages/entrada-1x-api
sudo php artisan cache:clear

Laravel Can't Save A File.

Solution: Check the permissions on the storage directory (see above).