Installation

Installation

The following instructions will assume a Debian-based system. AMsoil 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/fp7-ofelia/AMsoil.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

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 AMsoil 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 AMsoil/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 AMsoil 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)
• omni takes the request and passes it on to the FCGI server provided by AMsoil's Flask-FCGI plugin.
• The FGCI plugin translates the request to WSGI and sends it to the actual Flask application (which typically ends up in the FlaskXMLRPC).

To set the production up do the following:

• 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/*

Testing

Note AMsoil 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