=======
 Farol
=======

-------------------------------------------
A Security Advisory Management Web Platform
-------------------------------------------

:version: 0.1
:license: GPLv2+

Introduction
------------

Farol is a web platform dedicated to the management of Security Advisories.

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

Farol has a dependency on FarolLuz, Flask, and (obviously) Python.

Python can be either 2 or 3. 2.7 has been tested, as well as 3.3. 3.2 will not
work due to Flask (and dependencies) not being compatible with it.

Configuration
-------------

Configuration of Farol is done through a ``farol.cfg`` file that has to be set in the application *instance path*.

Deployment
----------

.. note:: While there are dozen of ways to deploy a WSGI application, this
          section documents a simple yet working and scalable way of doing it.

0. Get ``farol`` and ``farolluz`` source code.

1. Start with a virtualenv::

    virtualenv farol_env

2. Install FarolLuz and Farol in the virtualenv::

    farol_env/bin/pip install ./farolluz
    farol_env/bin/pip install ./farol

3. Install gunicorn in the virtualenv::

    farol_env/bin/pip install gunicorn

3b. (Optional) Test that farol can run in the virtualenv::

    farol_env/bin/gunicorn farol.main:app

   Visit the page http://localhost:8000 in a Web browser.

4. Configure Farol: set ``DEBUG`` to ``False``, and set the SECRET_KEY to
   something stable (and secret), so that it remains between reboot. The path
   to the configuration file can be found on the About page in the Debug
   Section.

4. Setup ``supervisord`` (that has previously been installed) to monitor the
   gunicorn process.

5. Setup ``nginx`` (that has previously also been installed) to proxy the
   gunicorn socket.

It is most probable that supervisord and nginx will also be used for other
services in your server.

Upgrade
-------

When new version are available, the following can be done:

Upgrade FarolLuz and Farol installation in the virtualenv::

  farol_env/bin/pip install --upgrade ./farolluz ./farol

Restart the gunicorn process::

  supervisorctl farol restart