Getting started¶

Prerequisites¶

Before starting, make sure your intended target system meets these requirements:

Python 3.5+
Mongo DB 3.4+
ElasticSearch 5+, not 6
Redis 3+
Node (tested with 6.11.2)
Yarn

Installation¶

These are the bare minimum installation steps required to get a basic XMM backend instance up and running from scratch. Please note that for local development you might want to adjust some arguments, as discussed in the next section.

Setup a virtual environment to seperate the global Python interpreter from the one that is supposed to execute XMM. On bash, to setup a new virtual environment called xmm_venv you do this:
```
virtualenv -p python3 xmm_venv
```
Install the XMM Core
- Directly from GitHub (Replace latest in the URL above with the version or branch you want to install):
```
pip install -e 'git+ssh://git@github.com/polynorm/poly-xmm-core.git@latest#egg=xmm'
```
- Or alternatively you can clone the project and install it using setuptools:
```
git clone git@github.com:polynorm/poly-xmm-core.git
pip install -e xmm-core
```
- Coming soon: Binary distributions that don’t require GitHub authentication.
Installing the xmm Python package will make the xmm-admin executable available in your $PATH, it allows you to bootstrap a new project:
```
# project_name must be a valid python identifier
xmm-admin generate project project_name
```

Note

(Replace “project_name” with a more suitable identifier that matches your project)

This will create a standalone project inside the project_name directory. If you want to start this project right now, you can call invoke. Alternatively, you can call e.g. invoke --host=127.0.0.1 --port=5000 `` to bind the host to ``127.0.0.1 and port to 5000:
```
cd project_name/
vi project_package/settings.py  # Important! Modify settings for your project!
invoke
```
This command will start five processes:
- Local development server on port 8100 (default)
- Celery task queue worker
- Celery beat task scheduler
- Asyncio Websocket server for push notifications
- Filesystem watchdog that monitors the media directory for changes
If you want to omit starting the Flask server, then call:
```
invoke all_tasks --noflask
```
If you want to omit starting celery beat and the worker, then call:
```
invoke all_tasks --nocelery
```
Call invoke help to see how to start each of these components individually. Each process can also be started manually either by calling the proper executable or running one of the available manage.py commands. manage.py is an executable file that has been generated inside the project directory and can be called directly:
```
./manage.py --help
```
Important: Every new project requires that its ElasticSearch index is built for the first time, so let’s to just that:
```
./manage.py elastic rebuild
```

Let’s also run the initial migration setup, this will not do anything but set a version number in your database, so we know which migrations to apply after an update:
./manage.py mongo migrate

Check the environment for some issues; e.g., if the correct Python, MongoDB, ElasticSearch and Redis versions are installed:
```
xmm-admin check
```
Alternatively, to check for pending deprecations, you can run this code snipped from inside an existing XMM project:
```
python -Wall:::xmm manage.py check
```
This will execute the same check command, but will also display all warnings found inside the xmm package.
Add a user to be able to login later, add the --superuser flag to grant all privileges:
```
./manage.py user create --superuser
```

Note

The next steps will guide you through the installation of the XMM UI.

Install the necessary frontend dependencies:

cd project_name/ # (if not already)
yarn install

Create and edit the config file if needed:

vi project_name/src/config/production/index.js

Link the UI-CLI tool:

cd xmm-ui/
yarn link
cd project_name/
yarn link xmm-ui

You should have access to the UI-CLI now and be able to build the bundle:
```
xmm-ui build
```
The XMM UI can be served by a server of your choice or with the provided node server with:
```
xmm-ui serve
```

Congratulations, you now have a XMM running on your system!

To start working, see the development section.