Upgrading to ME 1.10

Last updated 8 months ago

Introduction

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

There were significant changes introduced to how authentication works in version 1.10. The Laravel framework was introduced to the platform and powers the new REST-based Entrada API. This Entrada API is what now handles application authentication.

API Filesystem Location

The Entrada API application root lives in www-root/core/api/ and is accessed via a bootstrap at www-root/api/v2/index.php (or http://entrada-1x-me.localhost/api/v2).

Settings File Changes

The AUTH_PRODUCTION constant defined in www-root/core/config/settings.inc.php has changed to point to the new API. Make sure this is updated accordingly. It should look like this:

define("AUTH_PRODUCTION", ENTRADA_URL . "/api/v2/auth/login");

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

Apache .htaccess Changes

The www-root/.htaccess file in Entrada's web root is used primarily to provide pretty urls served by the Apache web server. We have added a new mod_rewrite rule in Entrada ME 1.10 that routes http requests from api/v2 to www-root/core/api/v2/index.php as well as provides additional authorization headers.

The following rules should be added to your www-root/.htacces file:

RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule .* - [e=HTTP_AUTHORIZATION:%1]
RewriteRule ^api/v2/(.*)$ api/v2/index.php/$1 [L,QSA]

The a complete and valid .htaccess file should look like:

RedirectMatch 404 /\\.git(/|$)
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule .* - [e=HTTP_AUTHORIZATION:%1]
RewriteCond %{REQUEST_FILENAME} -f [OR]
RewriteCond %{REQUEST_FILENAME} -l [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^.* - [L,QSA]
# Default Entrada Rules
RewriteRule ^api/v2/(.*)$ api/v2/index.php/$1 [L,QSA]
RewriteRule ^admin/(.*)$ admin.php/$1 [L,QSA]
RewriteRule ^community$ index.php/communities [L,QSA]
RewriteRule ^community/feeds(.*)$ community/serve-feeds.php$1 [L,QSA]
RewriteRule ^community/(.*)$ community/index.php/$1 [L,QSA]
RewriteRule ^images/dynamic/(.*)$ serve-images.php/$1 [L,QSA]
RewriteRule ^notices/(.*)$ serve-notices.php?g=$1 [L,QSA]
RewriteRule ^rss$ serve-rss.php [L,QSA]
RewriteRule ^rss/(.*)$ serve-rss.php/$1 [L,QSA]
RewriteRule ^podcasts/(.*)$ serve-podcasts.php?request=$1 [L,QSA]
RewriteRule ^calendars/(.*)$ api/calendar.api.php?request=$1 [L,QSA]
RewriteRule ^(.*)$ index.php/$1 [L,QSA]
</IfModule>

Please Note: Make sure this is changed for all of your environments (i.e. www-root/core/config/htaccess-staging.txt, www-root/core/config/htaccess-production.txt, etc.).

API Log File

There is a new Entrada API log file called api.log, which by default is located in www-root/core/storage/logs. This is where the Entrada API will log all authentication requests and you can usually see authentication errors logged here.

New Storage Directories

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

/app
/app/public
/framework
/framework/cache
/framework/cache/data
/framework/sessions
/framework/views

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.10 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/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

If you take a look at the HTML source code of Entrada ME 1.10's login page in the web browser and you do not see something that looks like the following, then you have not likely made the required changes to your institutions template files.

<script>
var ENTRADA_URL = 'http://entrada-1x-me.localhost';
var ENTRADA_RELATIVE = '';
var TEMPLATE_URL = 'http://entrada-1x-me.localhost/templates/default';
var TEMPLATE_RELATIVE = '/templates/default';
var JWT = '';
var API_URL = 'http://entrada-1x-me.localhost/api/v2';
</script>

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.

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 {} \;

The most common problem after upgrading to Entrada ME 1.10 is that you are unable to log in. You can't login?

Point your browser to ENTRADA_URL/api/v2 and you will probably see a big Whoops! That is Laravel telling you something is wrong.

Check the api.log in www-root/core/storage/logs/api.log. You might not see anything. That is ok. You can turn on debugging. To do this se the Enable Laravel Debug Mode section above.

If you have separate .htaccess files for your different environments, remember to add the re-write rule to all of them.

Also rember to check the settings file for your environment and make sure AUTH_PRODUCTION is set correctly.

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/api
sudo php artisan cache:clear

Laravel Can't Save A File.

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

Date and Time Formatting is Wonky.

Solution: You probably missed adding the new settings for date & time formatting in www-root/core/config/settings.inc.php.

If you have noticed anything else please add it to this documentation via a Fork and Pull-Request. I am sure there are things that I missed (MarneeDear@github).