.. _intro:

Getting started
===============

Prerequisites
-------------

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

- Python 3 installed (at least 3.6)
- Mongo DB server available (version 3.4 and up)
- ElasticSearch 5 Server
- Redis (version 2.8 and up)
- Node (tested with 6.11.2)
- Yarn

.. _installation:

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 :ref:`development<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 four 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

   To start off, every new project needs its ElasticSearch index 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::

      ./manage.py user create

.. 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 :ref:`UI-CLI<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 :ref:`development<development>` section.