Skip to content
This repository was archived by the owner on Apr 11, 2019. It is now read-only.

Installation

Jump to bottom
Michael Smart edited this page Jan 20, 2015 · 1 revision

Installation

The following instructions will assume a Debian-based system. eiSoil works well on my Mac too. Just use homebrew to install the required packages (basically substitute apt-get with brew).

First check out the code from github with git clone https://github.com/EICT/eiSoil.git

Base

  • Please make sure you have Python >= 2.7.
  • Install dependencies of M2Crypto and Nginx
    sudo apt-get install python-setuptools python-dev python-m2crypto python-openssl python-flup nginx
  • Install flup, flask, flask extension, blinker and pika via sudo easy_install flask Flask-XML-RPC python-dateutil blinker pika

Mac OSX (M2Crypto and Nginx via homebrew, the following packages may include some dependencies from gcf): brew install python brew install swig pip install M2Crypto brew install libxmlsec1 pip install python-dateutil brew install xmlsec1 pip install pyopenssl brew install nginx pip install flup

Common error
If you encounter a Permission denied error when starting eiSoil (see Development section) it is probably because easy_install did not change the privileges for the installed EGG files. Please look at the error message (e.g. Permission denied: '/SOMEPATH/xxx.egg/EGG-INFO/namespace_packages.txt'), and fix the permissions by executing: sudo chown -R YOURUSERNAME:admin /SOMEPATH/* (please replace the uppercase strings).

Plugins

  • Config Install sqlalchemy sudo easy_install sqlalchemy.
  • GENIv3RPC Install lxml sudo apt-get install libxml2-dev libxslt-dev && sudo easy_install lxml.

GCF setup

The GCF includes two major components to test an Aggregate Manager:

  • omni: A client for sending requests to the AM.
  • Clearinghouse (CH): A server to provide the client with the needed credentials to send to the AM (certificates and credentials).

To setup GCF please follow the following steps:

  • Install additional dependencies sudo apt-get install python-dateutil libxmlsec1 xmlsec1 libxmlsec1-openssl libxmlsec1-dev (alternativly see the INSTALL.txt).
  • Copy the current {gcf,omni}_config.sample files to {gcf,omni}_config files (found in the root folder) and adjust.
    • In gcf_config adjust the authority and the paths to the certificates if desired.
    • In omni_config adjust the authority and the [my_gcf], [Alice] and [Bob] sections.
  • Run python src/gen-certs.py to generate the experimenter, AM and CH certificates at ~/.gcf/. The paths to these certificates are set in omni_config.
  • Copy the trusted certificate issued by CH to the eiSoil trusted folder cp ~/.gcf/trusted_roots/ch-cert.pem deploy/trusted/ch-cert.pem.

More info info can be found via the GCF website.

Configuration

  • Start the server once via python src/main.py (so it can create the config defaults).
  • Copy the certificate issued by the clearinghouse if it was not done during previous steps (see "omni setup") cd eiSoil/admin && cp ~/.gcf/alice-cert.pem admin-cert.pem && cp ~/.gcf/alice-key.pem admin-key.pem
  • Run python admin/config_client.py --interactive to change the default AM configuration (also see the Configuration page)
  • Restart the server (just in case).

If you get an error from src/main.py which looks like this TypeError: shutdown() takes exactly 0 arguments (1 given) , we need to fix the werkzeug library: Go into /usr/lib/python2.7/SocketServer.py at the line 459 and change it to the following:

try:
  request.shutdown(socket.SHUT_WR)
except socket.error:
  pass
except TypeError: # << add this
  request.shutdown() # << add this

Asynchronous processing

Please start the worker server of eiSoil via ./main.py --worker if you have any plugin which needs job management. Please see more details via the Worker page.

Development setup

Use the config client to change the flask.fcgi to False and set flask.debug to True.

Please see the geni page for more information on the setup of an test bed environment.

Production setup

While the development server can be directly accessed by omni, the production server goes through the following steps:

  • omni sends the request to the webserver (nginx)
  • the webserver takes the request and passes it on to the FCGI server provided by eiSoil's Flask-FCGI plugin.
  • The FCGI plugin translates the request to WSGI and sends it to the actual Flask application (which typically ends up in the FlaskXMLRPC).

Nginx

To setup the production environment with nginx, please follow the next steps:

  • Configure nginx at file /etc/nginx/nginx.conf (you may copy the contents of deploy/nginx.conf.example and modify the include deploy/am.nginx.conf line)
  • Restart nginx
  • Use the config client to change the flask.fcgi to True
  • Run the sh generate_server_key.sh in deploy
  • Run python src/main.py to start the FCGI server

Note: On Mac installed via homebrew find the nginx logs in tail -f /usr/local/Cellar/nginx/1.2.2/logs/*

Apache

Here the instructions for Apache:

  • Use the config client to change the flask.fcgi to True
  • Run the sh generate_server_key.sh in eisoil's deploy folder
  • Install the apache module fastcgi_module (and ssl_module if it's not there)
  • Make sure the bootstrap file has permissions to be executable by all (chmod a+x src/main.py)
  • Make sure the permissions of logs and deploy are writable for anybody
chmod a+rwx log deploy
chmod a+rw log/eisoil.log deploy/*.db
  • Add the following lines to apache's fastcgi.conf file:
    FastCgiServer /path/to/eiSoil/src/main.py -port 9003
    ScriptAlias /SA /path/to/eiSoil/src/main.py
    ScriptAlias /MA /path/to/eiSoil/src/main.py
  • Add the following lines to apache's ssl.conf file:
    SSLOption +ExportCertData
    SSLCACertificateFile /path/to/ch-cert.pem
    SSLVerifyClient require
    SSLVerifyDepth 3
  • In apache's file deflate.conf, remove text/xml from the line AddOutputFilterByType DEFLATE, because gzip'ing the response confuses client.py about the size of the response.
  • If you have trouble, you may have to remove the bindAddress argument in line 76 the file src/vendor/flaskrpcs/flaskserver.py
  • Run python src/main.py to start the FCGI server
  • Restart apache

Many thanks to David Montana (BBN), who provided the input on deploying with Apache.
If there is any trouble, contact me via my Github profile.

Testing

Note eiSoil was tested with

  • Python 2.7.2
  • GCF 2.2 or 2.3 (omni)
  • Mac OSX 10.8.2

The implementation should work on other platforms too.

Next Steps

Please continue reading the Development section

Clone this wiki locally