System Installation
===================
    
Source code
-----------

If you have access the source code can be obtained by cloning from http://ac-software.tugraz.at/git/acnmr.git:

.. code::

    git clone http://ac-software.tugraz.at/git/acnmr.git 

Dependencies
------------

To run an instance of the ACNMR Server you need the following prerequisites.

- A web server that can host `WSGI <http://wsgi.readthedocs.org/en/latest/>`_ apps.
   - apache
   - gunicorn
- `sqlite <http://www.sqlite.org/>`_.
- `Couchdb <http://couchdb.apache.org/>`_
- Python with modules
   - `Rdkit <http://www.rdkit.org/>`_.
   - `Indigo  <http://ggasoftware.com/opensource/indigoand>`_
   - sqlite3
   - json
   - jsonschema
   - couchdb
   - flask

User authentication is not handled on flask level. For user authentication 
the authentication has to be provided by the web server e.g. simple authentication or some kind of
single-sign-on system.

WSGI Config
-----------

The configuration of the ACNMR server is done by an WSGI file. This file has to be provided to the 
web server to tell what code should be executed and with which environment.

.. code::

   import sys,os
   # The working directory of the app
   HOME='/home/appadmin/acnmrdev'   
   sys.path.insert(0, HOME)
   # add RDKit dir to python path
   sys.path.insert(0, '/opt/RDKit_2014_09_1') 
   
   # this is used to sign cookies should be  random string that is kept secret
   os.environ['SINMRSESSTOKEN']= '17486e6e' 
   # environment variabled that are needet for RDKit to work
   os.environ['RDBASE']='/opt/RDKit_2014_09_1/'
   # couchdb connection data
   os.environ['COUCHDBNAME']='acnmr'
   os.environ['COUCHDBURL']='http://127.0.0.1:5984/'
   os.environ['COUCHUSER']='username'
   os.environ['COUCHSECRET']='secret'
   # name of the sqlite database file
   os.environ['DATABASE']='NMR.db'
   # An alternative title tag
   os.environ['APPTITLE']='Sandbox'
   # username of the superuser. There must be one, or no one can add other users
   os.environ['ACNMROWNER']="superuser"
   # change directory
   os.chdir(HOME)
   # get the changes monitor module
   import acnmr.couchchanges   as couchchanges
   # start changes monitor process
   couchchanges.start()
   # import the app module that will be run by the WSGI container
   from acnmr.server import app as application
 
Configure Apache
----------------


Apache is not the fastest web server, but it offers a wide variety of authentication 
abilities and therefore it is the web server we choose.


Set global environment variables for RDkit
__________________________________________

In order for the RDKit module to find the dynamic libraries one 
must set the library path environment variable. This cannot be set in the 
WSGI file but must be set in the Apache environment variables section.

Add the location where your installation of RDKit resides to the Apache ``envvars`` file, or where appropriate:

.. code::
   
   export LD_LIBRARY_PATH=/opt/RDKit_2014_09_1/lib
 


Configure Apache Virtual Host
_____________________________

As the traffic might go through the Internet and you will have some kind of authentication HTTPS is
pretty much mandatory. Here is an example configuration for apache2 to 
setup a virtual host for HTTPS.
 
.. code:: bash
   
   <VirtualHost    ac-appserver.tugraz.at:443>
      ServerAdmin christian.meisenbichler@tugraz.at
      ServerName      ac-appserver.tugraz.at
      ErrorLog /var/log/apache2/acnmrdev-error.log
      CustomLog /var/log/apache2/acnmrdev-access.log combined
      # set the WSGI variables
      WSGIDaemonProcess acnmrdev user=appadmin group=appadmin threads=1
      WSGIScriptAlias / /home/appadmin/acnmrdev.wsgi
      # working directory 
      <Directory /home/appadmin/acnmrdev/>
         WSGIProcessGroup acnmrdev
         WSGIScriptReloading On
         LimitRequestBody 0
      </Directory>
      # you really must use SSL
      SSLEngine On
      SSLCertificateFile /etc/apache2/ssl/crt/ac-appserver.tugraz.at.pem
      SSLCertificateKeyFile /etc/apache2/ssl/key/ac-appserver.tugraz.at.key
      SSLCertificateChainFile  /etc/apache2/ssl/chain-5955-shib-test.tugraz.at.pem
      AllowEncodedSlashes On
      ProxyRequests Off
      KeepAlive Off
    
     
      <Location />
         SSLRequireSSL On
         SSLVerifyClient Off
         SSLVerifyDepth 1
         SSLOptions +StdEnvVars +StrictRequire
         WSGIProcessGroup acnmrdev
         SSLRenegBufferSize 104860000
         WSGIPassAuthorization On
         # example configuration to use HTTP basic auth  
         AuthType Basic
         AuthName "Authentication Required"
         AuthUserFile "/etc/htpasswd"
         Require valid-user
         Order allow,deny
         Allow from all
      </Location>
   </VirtualHost>