OpenConext EngineBlock
Build Status:
License
See the LICENSE-2.0.txt file
Disclaimer
See the NOTICE.txt file
Upgrading
See the UPGRADING.md file
(Theme) Development
Please see the wiki for information on how to get started with developing themes for OpenConext EngineBlock In short, themes require compilation which can be done by running the following commands:
(cd theme && npm install && grunt)
To setup the required tooling on the VM, the following steps might be useful:
cd /opt/openconext/OpenConext-engineblock/theme
sudo yum install npm
sudo npm install -g grunt grunt-cli
sudo yum install gem ruby-devel
gem install compass
(npm install && grunt)
System Requirements
- Linux
- Apache
- PHP 5.6:
- libxml
- MySQL > 5.x with settings:
- default-storage-engine=InnoDB
- default-collation=utf8_unicode_ci
- Manage
- NPM (optional for theme deployment)
- Grunt-cli (optional for theme deployment)
Note: While care was given to make EngineBlock as compliant as possible with mainstream Linux distributions, it is only regularly tested with RedHat Enterprise Linux and CentOS.
Installation
Note: you are advised to use OpenConext-Deploy to deploy OpenConext installations.
If you are reading this then you've probably already installed a copy of EngineBlock somewhere on the destination server, if not, then that would be step 1 for the installation.
If you do not use OpenConext-Deploy and have an installed copy and your server meets all the requirements above, then please follow the steps below to start your installation.
First, create an empty database
EXAMPLE
mysql -p
Enter password:
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 21
Server version: 5.0.77 Source distribution
Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
mysql> create database engineblock default charset utf8 default collate utf8_unicode_ci;
Then configure application config
Copy over the example configuration file from the docs directory to /etc/openconext/engineblock.ini:
sudo mkdir /etc/openconext
sudo cp docs/example.engineblock.ini /etc/openconext/engineblock.ini
For the development VM, you should replace all occurrences of demo.openconext.org with vm.openconext.org.
Then edit this file with your favorite editor and review the settings to make sure it matches your configuration. The settings in the example.engineblock.ini are a subset of all configuration options, which can be found, along with their default value in application/configs/application.ini.
Note that EngineBlock requires you to set a path to a logfile, but you have to make sure that this file is writable by your webserver user.
After that, you are required to ensure the application is in bootable state. Assuming you are preparing your installation for a production environment, you have to run:
composer prepare-env
should you not have access to a local installation of composer, a version is shipped with EngineBlock, replace
the composer
part above with bin/composer.phar
. This version is regularly updated, but may give warnings about
being outdated.
Install database schema updates
To install possible database updates, call doctrine migrations by using the following console command:
app/console doctrine:migrations:migrate --env=prod
Note:
EngineBlock requires database settings, without it doctrine migrate will not function. Furthermore, this assumes that
the application must use the production settings (--env=prod
), this could be replaced with dev
should you run a
development version.
Configure HTTP server
Configure a single virtual host, this should point to the web
directory:
DocumentRoot /opt/www/engineblock/web
It should also serve both the engine.yourdomain.example
and engine-api.yourdomain.example
domains.
Make sure the ENGINEBLOCK_ENV
is set, and that the SYMFONY_ENV
is set, this can be mapped from ENGINEBLOCK_ENV
as:
ENGINEBLOCK_ENV |
SYMFONY_ENV |
---|---|
production | prod |
acceptance | acc |
test | test |
vm | dev |
EXAMPLE
SetEnv ENGINEBLOCK_ENV !!ENV!!
SetEnv SYMFONY_ENV !!SF_ENV!!
Make sure you have the following rewrite rules (replace app.php
with app_dev.php
for development):
RewriteEngine On
# We support only GET/POST/HEAD
RewriteCond %{REQUEST_METHOD} !^(POST|GET|HEAD)$
RewriteRule .* - [R=405,L]
# If the requested url does not map to a file or directory, then forward it to index.php/URL.
# Note that the requested URL MUST be appended because Corto uses the PATH_INFO server variable
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-f
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ /app.php/$1 [L] # Send the query string to index.php
# Requests to the domain (no query string)
RewriteRule ^$ app.php/ [L]
Note that EngineBlock SHOULD run on HTTPS, you can redirect users from HTTP to HTTPS with the following Apache rewrite rules on a *:80 VirtualHost:
RewriteEngine on
RewriteCond %{SERVER_PORT} ^80$
RewriteRule ^(.*)$ https://%{SERVER_NAME}$1 [L,R=301]
Grab the front controller
Copy the app_dev.php.dist
file to the web
directory.
Openconext-engineblock $ cp app_dev.php.dist web/app_dev.php
Test your EngineBlock instance
Use these URLs to test your EngineBlock instance:
- http://engine.example.com, this should redirect you to the following URL
- https://engine.example.com, show a page detailing information about the capabilities
- https://engine.example.com/authentication/idp/metadata, this should present you with the IdP metadata of EngineBlock
- https://engine.example.com/authentication/sp/metadata, this should present you with the SP metadata of EngineBlock
- https://engine.example.com/authentication/proxy/idps-metadata, this should present you with the proxy IdP metadata
- https://engine-api.example.com, this should return an empty 200 OK response
Updating
It is recommended practice that you deploy engineblock in a directory that includes the version number and use a symlink to link to the 'current' version of EngineBlock.
EXAMPLE
.
..
engineblock -> engineblock-v1.6.0
engineblock-v1.5.0
engineblock-v1.6.0
If you are using this pattern, an update can be done with the following:
-
Download and deploy a new version in a new directory.
-
Check out the release notes in docs/release_notes/X.Y.Z.md (where X.Y.Z is the version number) for any additional steps.
-
Prepare your environment (see above)
SYMFONY_ENV=prod composer prepare-env
-
Run the database migrations script.
app/console doctrine:migrations:migrate --env=prod
-
Change the symlink.
Additional Documentation
Most additional documentation can be found in the wiki. If you want to help with development for instance, you can take a look at the Development Guidelines
Also, the following documentation can be found in the docs directory: