:orphan:

===================================
Local FactoryTX with Docker Compose
===================================

FactoryTX can be set up and run locally.

To prepare your local environment to run FactoryTX, please have the following
tools installed:

* `Git <https://git-scm.com/>`_
* `Docker <https://www.docker.com/>`_
* `docker-compose <https://docs.docker.com/compose/>`_

From a Terminal window, please create the Sight Machine directory and enter it.

.. code-block:: bash

    mkdir -p /opt/sightmachine && cd /opt/sightmachine

Next, clone the FactoryTX repository that you want to use into your local Sight
Machine directory. Please note that there two types of FactoryTX repositories:

* `factorytx-core <https://github.com/sightmachine/factorytx-core>`_: Contains
  the core FactoryTX logic and components
* **factorytx-<customer>**: Contains customer specific components built on
  factorytx-core

.. code-block:: bash

    cd /opt/sightmachine

    # If you want to clone factorytx-core
    git clone git@github.com:sightmachine/factorytx-core.git

    # If you want to clone a factorytx-<customer> repository
    # Remember to replace "<customer>" with the customer name
    git clone --recurse-submodules git@github.com:sightmachine/factorytx-<customer>.git

Then, set up the ``data`` directory. Files and subdirectories put into this
directory will be accessible for FactoryTX to use.

.. code-block:: bash

    mkdir -p /opt/sightmachine/data

Now, you're ready to run FactoryTX.

Build and run the Docker container with the following commands in a Terminal
window:

.. code-block:: bash

    # If you want to use a factorytx-core instance
    cd /opt/sightmachine/factorytx-core

    # Or if you want to use a factorytx-<customer> instance
    # Remember to replace "<customer>" with the customer name
    cd /opt/sightmachine/factorytx-<customer>

    FTX_NOAUTH=TRUE docker-compose -f docker-compose-local.yml up --build

**Note**: The ``-f`` flag allows the user to specify the YAML file for Docker to
use in building the container. To run the container in "detached" mode, add the
``-d`` flag. In effect, FactoryTX will run in the background and hide standard
output (stdout) logs.

To see the UI running, navigate to `localhost <http://localhost>`_ in your web
browser.

.. image:: img/FTX_UI_Config.png
    :alt: FactoryTX configuration UI

Authentication
==============

To enable authentication, you must create a hash of your password, and pass it
into the container as an environment variable. To create the hash make sure you
have ``werkzeug`` (v0.14+) installed (e.g. ``pip install werkzeug``). Next, in
the Python shell, run:

.. code-block:: Python

    from werkzeug.security import generate_password_hash
    print(generate_password_hash('your-password-here', method='pbkdf2:sha256'))
    # pbkdf2:sha256:50000$6qKJ5Oys$6fedf8fc3e197054559ad924a85cc0e51df26630b236f44dcb305f3b3f6076e3

Pass the user credentials as environment variables to your Docker container.

.. code-block:: bash

    FTX_USERNAME='admin' FTX_PW_HASH='pbkdf2:sha256:50000$UXhMIzBw$351dc988e8c851b70e25af75233f057efd20f697c37a46101dcceff800d1591e' docker-compose -f docker-compose-local.yml up --build -d