# Installation

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

- API:

    - Flask

    - gpxpy to parse gpx files

    - staticmap to generate a static map image from gpx coordinates

    - python-forecast.io to fetch weather data from Dark Sky (former forecast.io)

    - dramatiq for task queue

- Client:

    - React/Redux

    - Leaflet to display map

    - Recharts to display charts with elevation and speed

Sports and weather icons are made by Freepik from www.flaticon.com.

## Prerequisites

- PostgreSQL database (10+)

- Redis for task queue

- Python 3.7+

- Poetry (for installation from sources only)

- API key from Dark Sky [not mandatory]

- SMTP provider

- Yarn (for development only)

- Docker (for development only, to start MailHog or for evaluation purposes)

Note

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.

## Environment variables

Warning

Since FitTrackee 0.4.0, `Makefile.custom.config` is replaced by `.env`

The following environment variables are used by FitTrackee web application or the task processing library. They are not all mandatory depending on deployment method.

`FLASK_APP`
  Name of the module to import at flask run.
  `FLASK_APP` should contain `$(PWD)/fittrackee/__main__.py` with installation from sources, else `fittrackee`.

`HOST`

  FitTrackee host.

  Default

    0.0.0.0

`PORT`

  FitTrackee port.

  Default

    5000

`APP_SETTINGS`

  FitTrackee configuration.

  Default

    fittrackee.config.ProductionConfig

`APP_SECRET_KEY`

  FitTrackee secret key, must be initialized in production environment.

`APP_WORKERS`

  Number of workers spawned by Gunicorn.

  Default

    1

`APP_LOG`

  New in version 0.4.0.

  Path to log file

`UPLOAD_FOLDER`

  New in version 0.4.0.

  Directory containing uploaded files.

  Default

    fittrackee/uploads/

  Danger

  With installation from PyPI, the directory will be located in virtualenv directory if the variable is not initialized.

`DATABASE_URL`
  Database URL with username and password, must be initialized in production environment.
  For example in dev environment : `postgresql://fittrackee:fittrackee@localhost:5432/fittrackee`

  Danger

  Since SQLAlchemy update (1.4+), engine URL should begin with postgresql://.

`DATABASE_DISABLE_POOLING`

  New in version 0.4.0.

  Disable pooling if needed (when starting application with FitTrackee entry point and not directly with Gunicorn), see SqlAlchemy documentation.

  Default

    false

`UI_URL`

  FitTrackee URL, needed for links in emails.

`EMAIL_URL`

  New in version 0.3.0.

  Email URL with credentials, see Emails.

`SENDER_EMAIL`

  New in version 0.3.0.

  FitTrackee sender email address.

`REDIS_URL`

  New in version 0.3.0.

  Redis instance used by Dramatiq.

  Default

    local Redis instance (`redis://`)

`WORKERS_PROCESSES`

  New in version 0.3.0.

  Number of processes used by Dramatiq.

`TILE_SERVER_URL`

  New in version 0.4.0.

  Tile server URL (with api key if needed), see Map tile server.
  Since 0.4.9, it’s also used to generate static maps (to keep default server, see DEFAULT_STATICMAP)
  Default

    https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png

`MAP_ATTRIBUTION`

  New in version 0.4.0.

  Map attribution (if using another tile server), see Map tile server.

  Default

    &copy; <a href=”http://www.openstreetmap.org/copyright” target=”_blank” rel=”noopener noreferrer”>OpenStreetMap</a> contributors

`DEFAULT_STATICMAP 🆕`

  New in version 0.4.9.

  If True, it keeps using default tile server to generate static maps.

  Default

    False

`WEATHER_API_KEY`

  Changed in version 0.4.0: ⚠️ replaces `WEATHER_API`

  Dark Sky API key for weather data (not mandatory).

`REACT_APP_API_URL`

  FitTrackee API URL, only needed in dev environment.

### Deprecated variables

`REACT_APP_GPX_LIMIT_IMPORT`

  Deprecated since version 0.3.0: now stored in database

  Maximum number of gpx file in zip archive.

  Default

    10

`REACT_APP_MAX_SINGLE_FILE_SIZE`

  Deprecated since version 0.3.0: now stored in database

  Maximum size of a gpx or picture file.

  Default

    1MB

`REACT_APP_MAX_ZIP_FILE_SIZE`

  Deprecated since version 0.3.0: now stored in database

  Maximum size of a zip archive.

  Default

    10MB

`REACT_APP_ALLOW_REGISTRATION`

  Deprecated since version 0.3.0: now stored in database

  Allows users to register.

  Default

    true

`REACT_APP_THUNDERFOREST_API_KEY`

  Deprecated since version 0.4.0: see TILE_SERVER_URL

  ThunderForest API key.

Warning

Since FitTrackee 0.3.0, some applications parameters are now stored in database.
Related environment variables are needed to initialize database when upgrading from version prior 0.3.0.

### Emails

New in version 0.3.0.

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`

### Map tile server

New in version 0.4.0.

Default tile server is now OpenStreetMap’s standard tile layer (if environment variables are not initialized). The tile server can be changed by updating `TILE_SERVER_URL` and `MAP_ATTRIBUTION` variables (list of tile servers).

To keep using ThunderForest Outdoors, the configuration is:

- `TILE_SERVER_URL=https://{s}.tile.thunderforest.com/outdoors/{z}/{x}/{y}.png?apikey=XXXX` where XXXX is ThunderForest API key

- `MAP_ATTRIBUTION=&copy; <a href="http://www.thunderforest.com/">Thunderforest</a>, &copy; <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors`

Note

Check the terms of service of tile provider for map attribution

## From PyPI

Note

Recommended way on production.

Warning

Note that FitTrackee is under heavy development, some features may be unstable.

### Installation

- Create and activate a virtualenv

- Install FitTrackee with pip

    $ pip install fittrackee

- Create `fittrackee` database

Example :

    CREATE DATABASE fittrackee;
    CREATE USER fittrackee WITH PASSWORD '<PASSWORD>';
    GRANT ALL PRIVILEGES ON DATABASE fittrackee TO fittrackee;

- Initialize environment variables, see Environment variables

For instance, copy and update `.env` file from `.env.example` and source the file.

    $ nano .env
    $ source .env

- Upgrade database schema

    $ fittrackee_upgrade_db

- Initialize database

    $ fittrackee_init_data

- Start the application

    $ fittrackee

- Start task queue workers

    $ fittrackee_worker --processes 2

Note

To start application and workers with systemd service, see Deployment

### Upgrade

Warning

Before upgrading, make a backup of all data:
- database (with pg_dump for instance)
- upload directory (see Environment variables)

- Activate the virtualenv

- Upgrade with pip

    $ pip install -U fittrackee

- Update environment variables if needed and source environment variables file

    $ nano .env
    $ source .env

- Upgrade database if needed

    $ fittrackee_upgrade_db

- Restart the application and task queue workers.

## From sources

Warning

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

    $ yay poetry
    $ poetry --version
    Poetry 1.0.17

    # optional
    $ poetry config virtualenvs.in-project true

For other OS, see Poetry Documentation

### Installation

#### Dev environment

- Clone this repo:

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

- Create .env from example and update it (see Environment variables).

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

    $ make install-dev
    $ make install-db

- Start the server and the client:

    $ make serve

- Run dramatiq workers:

    $ make run-workers

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

#### Production environment

Warning

Note that FitTrackee is under heavy development, some features may be unstable.

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

    $ wget https://github.com/SamR1/FitTrackee/archive/v0.4.9.tar.gz
    $ tar -xzf v0.4.9.tar.gz
    $ mv FitTrackee-0.4.9 FitTrackee
    $ cd FitTrackee

- Create .env from example and update it (see Environment variables).

- Install Python virtualenv and all related packages:

    $ make install-python

- Initialize the database (after updating `db/create.sql` to change database credentials):

    $ make install-db

- Start the server and dramatiq workers:

    $ make run

Open http://localhost:5000, 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 for instance)
- upload directory (see Environment variables)

#### Dev environment

- Stop the application and pull the repository:

    $ git pull

- Update .env if needed (see Environment variables).

- Upgrade packages and database:

    $ make install-dev
    $ make upgrade-db

- Restart the server:

    $ make serve

- Run dramatiq workers:

    $ make run-workers

#### Prod environment

- Stop the application

- Change to the directory where FitTrackee directory is located

- Download the last release (for now, it is the release v0.4.9) and overwrite existing files:

    $ wget https://github.com/SamR1/FitTrackee/archive/v0.4.9.tar.gz
    $ tar -xzf v0.4.9.tar.gz
    $ cp -R FitTrackee-0.4.9/* FitTrackee/
    $ cd FitTrackee

- Update .env if needed (see Environment variables).

- Upgrade packages and database:

    $ make install-python
    $ make upgrade-db

- Restart the server and dramatiq workers:

    $ make run

## Deployment

There are several ways to start FitTrackee web application and task queue library. One way is to use a systemd services and Nginx to proxy pass to Gunicorn.

Examples (to update depending on your application configuration and given distribution):

- for application: `fittrackee.service`

    [Unit]
    Description=FitTrackee service
    After=network.target
    After=postgresql.service
    After=redis.service
    StartLimitIntervalSec=0

    [Service]
    Type=simple
    Restart=always
    RestartSec=1
    User=<USER>
    StandardOutput=syslog
    StandardError=syslog
    SyslogIdentifier=fittrackee
    Environment="APP_SECRET_KEY="
    Environment="APP_LOG="
    Environment="UPLOAD_FOLDER="
    Environment="DATABASE_URL="
    Environment="UI_URL="
    Environment="EMAIL_URL="
    Environment="SENDER_EMAIL="
    Environment="REDIS_URL="
    Environment="TILE_SERVER_URL="
    Environment="MAP_ATTRIBUTION="
    Environment="WEATHER_API_KEY="
    WorkingDirectory=/home/<USER>/<FITTRACKEE DIRECTORY>
    ExecStart=/home/<USER>/<FITTRACKEE DIRECTORY>/.venv/bin/gunicorn -b 127.0.0.1:5000 "fittrackee:create_app()" --error-logfile /home/<USER>/<FITTRACKEE DIRECTORY>/gunicorn.log
    Restart=always

    [Install]
    WantedBy=multi-user.target

Note

More information on Gunicorn documentation

- for task queue workers: `fittrackee_workers.service`

    [Unit]
    Description=FitTrackee task queue service
    After=network.target
    After=postgresql.service
    After=redis.service
    StartLimitIntervalSec=0

    [Service]
    Type=simple
    Restart=always
    RestartSec=1
    User=<USER>
    StandardOutput=syslog
    StandardError=syslog
    SyslogIdentifier=fittrackee_workers
    Environment="FLASK_APP=fittrackee"
    Environment="APP_SECRET_KEY="
    Environment="APP_LOG="
    Environment="UPLOAD_FOLDER="
    Environment="DATABASE_URL="
    Environment="UI_URL="
    Environment="EMAIL_URL="
    Environment="SENDER_EMAIL="
    Environment="REDIS_URL="
    WorkingDirectory=/home/<USER>/<FITTRACKEE DIRECTORY>
    ExecStart=/home/<USER>/<FITTRACKEE DIRECTORY>/.venv/bin/flask worker --processes <NUMBER OF PROCESSES>
    Restart=always

    [Install]
    WantedBy=multi-user.target

- Nginx configuration:

    server {
        listen 443 ssl;
        server_name example.com;
        ssl_certificate fullchain.pem;
        ssl_certificate_key privkey.pem;

        location / {
            proxy_pass http://127.0.0.1:5000;
            proxy_redirect    default;
            proxy_set_header  Host $host;
            proxy_set_header  X-Real-IP $remote_addr;
            proxy_set_header  X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header  X-Forwarded-Host $server_name;
        }
    }

    server {
        listen 80;
        server_name example.com;
        location / {
            return 301 https://example.com$request_uri;
        }
    }

Note

If needed, update configuration to handle larger files (see client_max_body_size).

## Docker

### Installation

New in version 0.4.4.

For evaluation purposes , docker files are available, installing FitTrackee from sources.

- To install FitTrackee with database initialisation and run the application and dramatiq workers:

    $ git clone https://github.com/SamR1/FitTrackee.git
    $ cd FitTrackee
    $ make docker-build docker-run docker-init

Open http://localhost:5000, log in as admin (the email is admin@example.com and the password mpwoadmin) or register.

Open http://localhost:8025 to access MailHog interface (email testing tool)

- To stop Fittrackee:

    $ make docker-stop

- To start Fittrackee (application and dramatiq workers):

    $ make docker-run-all

- To run shell inside Fittrackee container:

    $ make docker-shell

### Client Development

New in version 0.4.10.

- in order to start client with React dev tools, install fittrackee_client

    $ make docker-build-client

- start React app

    $ make docker-serve-client