Configuration

A project is configured with its settings.py file inside the project package, or as otherwise specified by the 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 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.

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[.*]