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
- php 7.1 + (if your OS does not support it you will need an exterenal repo, e.g. ppa:ondrej/php)
- 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)
- 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
(fix problems if any, usually missing extensions)
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>
First, create a myslq/mariadb database and the corresponding user.
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.
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
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. firstname.lastname@example.org
You also have to let HEXAA know about the Service Providers available. These are enumerated in:
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:
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.
For debugging, see:
- php error logs, at standard location
- symfony logs at app/logs
You can also edit .:
By default it is only accessible from localhost.