Installation of hexaa-backend (for v2 RC)

Note

This description is for the HEXAA2 version and many details are temporary (mostly around git). Also, for HEXAA v2 docker will be the easy way of installation.

This description for non-docker installations.

Manual (non-docker) installation

Requirements

  • php 7.1 + (if your OS does not support it you will need an exterenal repo, e.g. ppa:ondrej/php)
    • Extensions:
      • php-curl
      • php-intl
      • php-xml
      • php-mysql
      • php-memcached
      • php-bcmath
  • composer (the linux command line tool)
  • mysql 5.5 + or the equivalent mariadb version
  • apache + shibboleth (all non-deprecated versions should work)
  • unzip (the command line tool, for composer)
  • git (for cloning the repo)
  • memcached
  • Some mail sending solution, e.g. sendmail, or an smtp server, depending on the desired configuration. (HEXAA is based on symfony, which in turn uses swiftmailer. See the symfony configuration for swiftmailer https://symfony.com/doc/current/reference/configuration/swiftmailer.html)

Installation of the code

Get the code my cloning the git repo

$ cd /opt
$ git clone https://github.com/hexaaproject/hexaa-backend.git

Switch to the latest branch (this will not be necessary in the final version!)

cd hexaa-backend
git checkout docker-for-dev

Run composer

composer install

(fix problems if any, usually missing extensions)

Apache protection

In terms of apache configuration, we delegate the auth config to the .htaccess file created by smyfony:

Alias /hexaa-backend /opt/hexaa-backend/web
<Directory /opt/hexaa-backend/web>
        AllowOverride All
        Require all granted
</Directory>

Configuration

First, create a myslq/mariadb database and the corresponding user.

Then, edit

app/config/parameters.yml

In parameters.yml, configure

  • database credentials
  • mail_transport (for more info see the link in the Requirments section above)
  • secret (this is for symfony internal. See the comment on how to generate)
  • hexaa_ui_url: where the UI will be (if any) don't add '/' to the end
  • insertSomeHere : now this is tricky. For arcane performance-saving reasons we will replace the key here and leave the value as is. e.g. 5syhzz5ornk0xnyj8f2q5dk9n4e47nc19emexuc6: defaultMasterKey

  • hexaa_from_address: the sender of the outgoing emails

Now we create the database schema:

php app/console doctrine:schema:update --force

Depending on your OS, you might run into a bug in the OS-php7.1 integration. This will manifest itself as a runtime php error about the inability of accessing /var/lig/php5. (yes php5!) In this case you will have to:

mkdir /var/lib/php5
chown -R www-data /var/lib/php5

This will hopefully be resolved when php7.1 will be more common.

For defining who the platform administrators will be, edit

hexaa_admins.yml

Add here the IDs of the platform admins. The most common configuration of HEXAA is based on eduPersonPrincipalName. Insuch case here are some eppn values are enumerated, e.g. user@example.com

You also have to let HEXAA know about the Service Providers available. These are enumerated in:

hexaa_entityids.yml

The accurate contact information is crucial here, because users can become Service Managers by being able to receiving a token sent in email by HEXAA. See the User Guide for details.

You will be most probably generating this from federate metadata. In case you are using XML-based metadata, you can use https://github.com/szabogyula/hexaa-service-entityids-generator

After you change the configuration, it is worth clearing the chache, which may or may not already generated.

rm -r app/cache/*
chown www-data app/cache

Also, make the log directory writable for the web server

chown -R www-data app/logs/

You can verify if hexaa-backend is deployed correctly by visting the auto-generated API doc:

https://<your host>/hexaa-backend/doc

This is an interactive doc, which helps you issue API queries. The access of this doc might be restricted by Apache Rules, although the API doc does not give extra permissions than having access to the API itself.

If you plan to deploy the hexaa-ui on the same host and not experiment with the API at all, you should restrict the access for both to localhost.

Troubleshooting

For debugging, see:

  • php error logs, at standard location
  • symfony logs at app/logs

You can also edit .:

web/app_dev.php

By default it is only accessible from localhost.