FitTrackee/docsrc/source/installation.rst

Installation
############

This application is written in Python (API) and Javascript (client):

- API:
    - Flask
    - `gpxpy <https://github.com/tkrajina/gpxpy>`_ to parse gpx files
    - `staticmap <https://github.com/komoot/staticmap>`_ to generate a static map image from gpx coordinates
    - `python-forecast.io <https://github.com/ZeevG/python-forecast.io>`_ to fetch weather data from `Dark Sky <https://darksky.net>`__ (former forecast.io)
    - `dramatiq <https://flask-dramatiq.readthedocs.io/en/latest/>`_ for task queue
- Client:
    - React/Redux
    - `Leaflet <https://leafletjs.com/>`__ to display map
    - `Recharts <https://github.com/recharts/recharts>`__ to display charts with elevation and speed

Sports and weather icons are made by `Freepik <https://www.freepik.com/>`__ from `www.flaticon.com <https://www.flaticon.com/>`__.

Prerequisites
~~~~~~~~~~~~~

-  PostgreSQL database (10+)
-  Redis for task queue
-  Python 3.7+
-  `Poetry <https://poetry.eustace.io>`__
-  `Yarn <https://yarnpkg.com>`__ and
   `serve <https://github.com/zeit/serve>`__
-  API key from `ThunderForest <http://thunderforest.com>`__
-  API key from `Dark Sky <https://darksky.net/dev>`__ [not mandatory]
-  SMTP provider


Installation
~~~~~~~~~~~~

| The following steps describe an installation on Linux systems (tested
  on Debian and Arch).
| On other OS, some issues can be encountered and adaptations may be
  necessary.

.. warning::
    Since FitTrackee 0.2.1, Python packages installation needs Poetry. To install it on ArchLinux:

    .. code-block:: bash

        $ yay poetry
        $ poetry --version
        Poetry 1.0.5

        # optional
        $ poetry config virtualenvs.in-project true

    For other OS, see `Poetry Documentation <https://python-poetry.org/docs/#installation>`__


Dev environment
^^^^^^^^^^^^^^^

-  Clone this repo:

.. code:: bash

   $ git clone https://github.com/SamR1/FitTrackee.git
   $ cd FitTrackee

-  Update **Makefile.config** file if needed and copy/paste the
   **ThunderForest** and **Dark Sky** API keys value in
   **Makefile.custom.config** file (see `Environment variables <installation.html#environment-variables>`__).

-  Install Python virtualenv, React and all related packages and
   initialize the database:

.. code:: bash

   $ make install-dev
   $ make install-db

-  Start the server and the client:

.. code:: bash

   $ make serve

-  Run dramatiq workers:

.. code:: bash

   $ make run-workers

Open http://localhost:3000 and login (the email is ``admin@example.com``
and the password ``mpwoadmin``) or register

Prod environment
^^^^^^^^^^^^^^^^

.. warning::
    Note that FitTrackee is not production-ready yet

-  Download the last release (for now, it is the beta release v0.3.0):

.. code:: bash

   $ wget https://github.com/SamR1/FitTrackee/archive/v0.3.0-beta.tar.gz
   $ tar -xzf v0.3.0-beta.tar.gz
   $ mv FitTrackee-0.3.0-beta FitTrackee
   $ cd FitTrackee

-  Update **Makefile.config** file if needed and copy/paste the
   **ThunderForest** and **Dark Sky** API keys value in
   **Makefile.custom.config** file (see `Environment variables <installation.html#environment-variables>`__).

-  Install Python virtualenv, React and all related packages and
   initialize the database:

.. code:: bash

   $ make install
   $ make install-db

-  Build the client:

.. code:: bash

   $ make build-client

-  Start the server and the client:

.. code:: bash

   $ make run

-  Run dramatiq workers:

.. code:: bash

   $ make run-workers

Open http://localhost:3000, log in as admin (the email is
``admin@example.com`` and the password ``mpwoadmin``) and change the
password

Upgrade
~~~~~~~

.. warning::
    | Before upgrading, make a backup of all data:
    | - database (with `pg_dump <https://www.postgresql.org/docs/11/app-pgdump.html>`__ for instance)
    | - upload directory: **FitTrackee/fittrackee_api/fittrackee_api/uploads/**


Dev environment
^^^^^^^^^^^^^^^

- Stop the application and pull the repository:

.. code:: bash

   $ git pull

- Update **Makefile.config** and **Makefile.custom.config** file if needed

- Upgrade packages and database:

.. code:: bash

   $ make install-dev
   $ make upgrade-db

- Restart the server and the client:

.. code:: bash

   $ make serve


Prod environment
^^^^^^^^^^^^^^^^

``TODO``


Environment variables
~~~~~~~~~~~~~~~~~~~~~

The following environment variables must be defined in **Makefile.custom.config**:

.. cssclass:: table-bordered table-striped

===================================== ======================================= ====================================
variable                              description                             app default value
===================================== ======================================= ====================================
``REACT_APP_API_URL``                 Fittrackee API URL                      no default value, must be initialized
``REACT_APP_GPX_LIMIT_IMPORT``        max. number of gpx file in zip archive  10 (*deprecated in 0.3.0*)
``REACT_APP_MAX_SINGLE_FILE_SIZE``    max. size of a gpx or picture file      1MB (*deprecated in 0.3.0*)
``REACT_APP_MAX_ZIP_FILE_SIZE``       max. size of a zip archive              10MB (*deprecated in 0.3.0*)
``REACT_APP_ALLOW_REGISTRATION``      allows users to register                true (*deprecated in 0.3.0*)
``REACT_APP_THUNDERFOREST_API_KEY``   ThunderForest API key                   no default value, must be initialized
``UI_URL``                            application URL                         no default value, must be initialized
``EMAIL_URL``                         email URL with credentials              no default value, must be initialized (see below)
``SENDER_EMAIL``                      application sender email address        no default value, must be initialized
``REDIS_URL``                         Redis instance used by Dramatiq         local Redis instance
``WORKERS_PROCESSES``                 number of process used by Dramatiq      no default value, must be initialized
===================================== ======================================= ====================================

.. warning::
    Since FitTrackee 0.3.0, some applications parameters are now stored in database.
    Related environment variables are needed to initialize database.

Emails
^^^^^^

To send emails, a valid ``EMAIL_URL`` must be provided:

- with an unencrypted SMTP server: ``smtp://username:password@smtp.example.com:25``
- with SSL: ``smtp://username:password@smtp.example.com:465/?ssl=True``
- with STARTTLS: ``smtp://username:password@smtp.example.com:587/?tls=True``