.. _deployment:

Configuration
=============

A project is configured with its ``settings.py`` file
inside the project package, or as otherwise specified
by the :envvar:`XMM_PROJECT_MODULE` environment variable.

The settings file is a basic Python file, you can use
any Python code inside of it, just like you normally would.

At the very least, a project's configuration file must define
the following::

   # Salt used in cryptographic functions, keep this secret!
   SECRET_KEY = 'a very random string 123'

   # MongoDB connection string
   MONGODB_URL = 'mongodb://user[:pass]@host:port/database'

   # Redis connection string
   REDIS_URL = 'redis://[:password]@localhost:6379/0'

The project settings template generated will provide a basic
boilerplate including these and many more useful options.

Please refer to the list of all available :ref:`settings`.

Deployment
==========

Once a project has been configured, the individual parts of
the XMM setup need to be deployed.

Flask web app
-------------

The web application server provides the primary API endpoints
that the frontend interacts with. Without it, nothing works.

Flask provides an app variable that can be used with a WSGI
server, such as ``gunicorn`` or ``uwgsi``.
The default import path for it as generated by the ``startproject``
command is ``xmmapp.wsgi:app``.

Websocket server
----------------

A simple websocket server is required to provide updates in real time
to users.

It can be run directly by issuing the command::

   $ python manage.py websocket

Please see the included ``--help`` options for available parameters.

Media watchdog
--------------

The files watchdog monitors the data directory for uploads or changes
to files made by other sources to keep them up to date in the database.

It can be run directly by issuing the command::

   $ python manage.py media watchdog


Celery worker & beat
--------------------

The task queue consists of two parts, a worker pool and a beat scheduler.

To run the worker pool, issue the command::

   $ export XMM_SETTINGS_MODULE=xmmapp.settings
   $ celery -A xmm.celery worker

Please check the `celery workers documentation`_ to specify options such as number of workers in the pool.

In order to run periodic tasks, the beat scheduler service needs to run as well::

   $ export XMM_SETTINGS_MODULE=xmmapp.settings
   $ celery -A xmm.celery beat -S xmm.util.schedulers.MongoEngineScheduler

Please check the `celery beat documentation`_ to specify options such as loglevel.

.. warning:: Important! The beat scheduler service must only run once for a given system, as
             multiple instances might cause duplicate tasks being started.
             The beat scheduler does not execute the tasks but only queues them into the worker
             pool once the tasks are due.

.. _celery workers documentation: http://docs.celeryproject.org/en/latest/userguide/workers.html#starting-the-worker
.. _celery beat documentation: http://docs.celeryproject.org/en/latest/userguide/periodic-tasks.html#starting-the-scheduler


Deprecation Warnings
====================

You may run into less useful DeprecationWarnings from PyMongo caused by MongoEngine.
These warnings can be suppressed by passing this argument to the Python interpreter::

    python -W ignore::DeprecationWarning:pymongo[.*]