benoit@0: =======
benoit@0:  Farol
benoit@0: =======
benoit@0: 
benoit@0: -------------------------------------------
benoit@0: A Security Advisory Management Web Platform
benoit@0: -------------------------------------------
benoit@0: 
benoit@0: :version: 0.1
benoit@0: :license: GPLv2+
benoit@0: 
benoit@0: Introduction
benoit@0: ------------
benoit@0: 
benoit@0: Farol is a web platform dedicated to the management of Security Advisories.
benoit@1: 
benoit@1: Dependencies
benoit@1: ------------
benoit@1: 
benoit@1: Farol has a dependency on FarolLuz, Flask, and (obviously) Python.
benoit@1: 
benoit@1: Python can be either 2 or 3. 2.7 has been tested, as well as 3.3. 3.2 will not
benoit@1: work due to Flask (and dependencies) not being compatible with it.
benoit@1: 
benoit@1: Configuration
benoit@1: -------------
benoit@1: 
benoit@1: Configuration of Farol is done through a ``farol.cfg`` file that has to be set in the application *instance path*.
benoit@1: 
benoit@1: Deployment
benoit@1: ----------
benoit@1: 
benoit@1: .. note:: While there are dozen of ways to deploy a WSGI application, this
benoit@1:           section documents a simple yet working and scalable way of doing it.
benoit@1: 
benoit@1: 0. Get ``farol`` and ``farolluz`` source code.
benoit@1: 
benoit@1: 1. Start with a virtualenv::
benoit@1: 
benoit@1:     virtualenv farol_env
benoit@1: 
benoit@1: 2. Install FarolLuz and Farol in the virtualenv::
benoit@1: 
benoit@1:     farol_env/bin/pip install ./farolluz
benoit@1:     farol_env/bin/pip install ./farol
benoit@1: 
benoit@1: 3. Install gunicorn in the virtualenv::
benoit@1: 
benoit@1:     farol_env/bin/pip install gunicorn
benoit@1: 
benoit@1: 3b. (Optional) Test that farol can run in the virtualenv::
benoit@1: 
benoit@1:     farol_env/bin/gunicorn farol.main:app
benoit@1: 
benoit@1:    Visit the page http://localhost:8000 in a Web browser.
benoit@1: 
benoit@1: 4. Configure Farol: set ``DEBUG`` to ``False``, and set the SECRET_KEY to
benoit@1:    something stable (and secret), so that it remains between reboot. The path
benoit@1:    to the configuration file can be found on the About page in the Debug
benoit@1:    Section.
benoit@1: 
benoit@1: 4. Setup ``supervisord`` (that has previously been installed) to monitor the
benoit@1:    gunicorn process.
benoit@1: 
benoit@1: 5. Setup ``nginx`` (that has previously also been installed) to proxy the
benoit@1:    gunicorn socket.
benoit@1: 
benoit@1: It is most probable that supervisord and nginx will also be used for other
benoit@1: services in your server.
benoit@1: 
benoit@1: Upgrade
benoit@1: -------
benoit@1: 
benoit@1: When new version are available, the following can be done:
benoit@1: 
benoit@1: Upgrade FarolLuz and Farol installation in the virtualenv::
benoit@1: 
benoit@1:   farol_env/bin/pip install --upgrade ./farolluz ./farol
benoit@1: 
benoit@1: Restart the gunicorn process::
benoit@1: 
benoit@1:   supervisorctl farol restart
benoit@1: