added documentation to README.md

README.md

 [![Build Status](https://git-r3lab.uni.lu/sascha.herzinger/fractalis/badges/master/build.svg)](https://git-r3lab.uni.lu/sascha.herzinger/fractalis/builds/)
-[![Coverage Report](https://git-r3lab.uni.lu/sascha.herzinger/fractalis/badges/master/coverage.svg)](https://git-r3lab.uni.lu/sascha.herzinger/fractalis/builds/)
+[![Coverage Report](https://git-r3lab.uni.lu/sascha.herzinger/fractalis/badges/master/coverage.svg)](https://git-r3lab.uni.lu/sascha.herzinger/fractalis/builds/)
 
-There is no official documentation for deploying Fractalis, **yet**.
-Running it in a development environment is very simple, though.
-Just have a look at *.gitlab-ci.yml* which demonstrates the setup for a vanilla CentOS installation.
\ No newline at end of file
+### About
+This is the back-end component of the Fractalis project. It is a computational node that is responsible for the MicroETL process and the execution of analytical tasks.
+
+### Installation (Docker)
+The easiest and most convenient way to deploy Fractalis is using Docker.
+All necessary information can be found here [Fractalis-Docker](https://git-r3lab.uni.lu/Fractalis/Fractalis-Docker).
+
+### Installation (Manual)
+If you do not want to use docker or want a higher level of control of the several components, that's fine. In fact it isn't difficult to setup Fractalis manually.
+We highly recommend having a look at the [CI File](https://git-r3lab.uni.lu/Fractalis/fractalis/blob/master/.gitlab-ci.yml) that is used to setup a *very* simple environment in which tests can be executed. For a more advanced setup in production please follow these steps:
+- Install and run [Redis](https://redis.io/), which is available for most Linux distributions. This instance must be accessible by the web service and the workers.
+- Install and run [RabbitMQ](https://www.rabbitmq.com/), which is available in most Linux distributions. This instance must be accessible by the web service and the workers.
+- Install Fractalis via `pip3 install fractalis`. Please note that Fractalis requires Python3.4 or higher. This must be installed on all machines that will run the web service or the workers.
+- Install required all required R packages. We won't list these packages excplicitely, as they can change frequently. Please refer instead to the [CI File](https://git-r3lab.uni.lu/Fractalis/fractalis/blob/master/.gitlab-ci.yml), which is *always* up-to-date, as a new version of Fractalis is only released when this script works. This must be installed on all machines that will run the web service or the workers.
+- Run and expose the Fractalis web service with whatever tools you want. We recommend **gunicorn** and **nginx**, but others should work, too. Here is an example how we run the Fractalis web service in the [Dockerfile.web](https://git-r3lab.uni.lu/Fractalis/Fractalis-Docker/blob/master/Dockerfile.web). You likely want to use nginx on top of that.
+- Run workers on any machine that you want. (For a simple setup this can be the very same machine that the web service runs on). Here is an example how we run a Fractalis worker in the [Dockerfile.worker](https://git-r3lab.uni.lu/Fractalis/Fractalis-Docker/blob/master/Dockerfile.worker)
+
+### Configuration
+All setups, manual, docker, or any future setup method will always rely on the environment variable `FRACTALIS_CONFIG` for configuration.
+This variable must be a) a valid python file (.py) and b) be available on all instances that host a Fractalis web service or a Fractalis worker.
+Use the [default settings](https://git-r3lab.uni.lu/Fractalis/fractalis/blob/master/fractalis/config.py) as an example for your own configuration file.
+Please note, that all this files combines [Flask Settings](http://flask.pocoo.org/docs/0.12/config/), [Celery Settings](http://docs.celeryproject.org/en/latest/userguide/configuration.html), and Fractalis Settings, which are all listed and documented within this file. A word of warning: Please don't overwrite default settings if you don't know what you are doing. This might have severe implications for security or might cause Fractalis to not work correctly.
+
+### Citation
+Manuscript is in preparation.

fractalis/config.py

@@ -25,9 +25,13 @@ CELERY_TASK_RESULT_EXPIRES = timedelta(hours=1)
 CELERYD_HIJACK_ROOT_LOGGER = False
 
 # Fractalis
+# Location of cache and temporary files
 FRACTALIS_TMP_DIR = os.path.abspath(os.path.join(os.sep, 'tmp', 'fractalis'))
+# How long to store files in the cache
 FRACTALIS_CACHE_EXP = timedelta(days=10)
+# Should the Cache be encrypted? This might impact performance for little gain!
 FRACTALIS_ENCRYPT_CACHE = False
+# Location of your the log configuration file.
 FRACTALIS_LOG_CONFIG = os.path.join(os.path.dirname(__file__), 'logging.yaml')
 
 

requirements.txt

@@ -5,6 +5,7 @@ ipython
 ipdb
 pytest
 pytest-runner
+pytest-cov
 pytest-mock
 responses
 twine

setup.cfg

-[aliases]
-test = pytest
-
 [metadata]
 description-file=README.md
-
-[tool:pytest]
-addopts =
-    --capture=no
-    --color=yes
-    --verbose
-testpaths = tests