# Installation - FitTrackee 0.7.28 documentation

Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# Installation

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

- API:

    - Flask

    - gpxpy to parse gpx files

    - staticmap to generate a static map image from gpx coordinates

    - dramatiq for task queue

    - Authlib for OAuth 2.0 Authorization support

    - Flask-Limiter for API rate limits

- Client:

    - Vue3/Vuex

    - Leaflet to display map

    - Chart.js to display charts with elevation and speed

Logo, some sports and weather icons are made by Freepik from www.flaticon.com.
FitTrackee also uses icons from Fork Awesome.

## Prerequisites

- mandatory

    - Python >= 3.8.1

    - PostgreSQL 12+

- optional

    - Redis for task queue (if email sending is enabled and for data export requests) and API rate limits

    - SMTP provider (if email sending is enabled)

    - API key from a weather data provider

    - Poetry (for installation from sources only)

    - Node 18+ and Yarn (for development only)

    - Docker and Docker Compose (for development or evaluation purposes)

Note

If registration is enabled, it is recommended to set Redis and a SMTP provider for email sending and data export requests.

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:

    `127.0.0.1`

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.

  Warning

  Use a strong secret key. This key is used in JWT generation.

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.

  Absolute path to the directory where `uploads` folder will be created.

  Default:

    `<application_directory>/fittrackee`

  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`

  Warning

  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.

  Changed in version 0.6.5.

  Default:

    empty string

  Danger

  If the email URL is empty, email sending will be disabled.

  Warning

  If the email URL is invalid, the application may not start.

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 and Flask-Limiter.

  Default:

    local Redis instance (`redis://`)

WORKERS_PROCESSES

  New in version 0.3.0.

  Number of processes used by Dramatiq.

API_RATE_LIMITS

  New in version 0.7.0.

  API rate limits, see API rate limits.

  Default:

    `300 per 5 minutes`

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)

  Changed in version 0.7.23.

  The default URL is updated: OpenStreetMap’s tile server no longer requires subdomains.
  Default:

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

STATICMAP_SUBDOMAINS

  New in version 0.6.10.

  Some tile servers require a subdomain, see Map tile server.
  For instance: “a,b,c” for OSM France.
  Default:

    empty string

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 staticmap default tile server to generate static maps (OSM tile server since staticmap 0.5.6 (Komoot.de tile server before this version)).
  Otherwise, it uses the tile server set in TILE_SERVER_URL.

  Changed in version 0.6.10.

  This variable is now case-insensitive.
  If `False`, depending on tile server, subdomains may be mandatory.
  Default:

    `False`

WEATHER_API_KEY

  Changed in version 0.4.0: ⚠️ replaces `WEATHER_API`

  Weather API key (not mandatory), see `WEATHER_API_PROVIDER`.

WEATHER_API_PROVIDER 🆕

  New in version 0.7.11.

  Provider for weather data (not mandatory), see Weather data.

VITE_APP_API_URL

  Changed in version 0.7.26: ⚠️ replaces `VUE_APP_API_URL`

### 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`

Warning

If the email URL is invalid, the application may not start.
Sending emails with Office365 may not work if SMTP auth is disabled.

Changed in version 0.5.3.

Credentials can be omitted: `smtp://smtp.example.com:25`.
If `:<port>` is omitted, the port defaults to 25.

Warning

Since 0.6.0, newly created accounts must be confirmed (an email with confirmation instructions is sent after registration).

Emails sent by FitTrackee are:

- account confirmation instructions

- password reset request

- email change (to old and new email addresses)

- password change

- notification when a data export archive is ready to download (new in 0.7.13)

Changed in version 0.6.5.

For single-user instance, it is possible to disable email sending with an empty `EMAIL_URL` (in this case, no need to start dramatiq workers).

A CLI is available to activate account, modify email and password and handle data export requests.

Changed in version 0.7.24.

Password can be encoded if it contains special characters. For instance with password `passwordwith@and&and?`, the encoded password will be: `passwordwith%40and%26and%3F`.

### 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.

Changed in version 0.6.10.

Since the tile server can be used for static map generation, some servers require a subdomain.

For instance, to set OSM France tile server, the expected values are:

- `TILE_SERVER_URL=https://{s}.tile.openstreetmap.fr/osmfr/{z}/{x}/{y}.png`

- `MAP_ATTRIBUTION='fond de carte par <a href="http://www.openstreetmap.fr/mentions-legales/" target="_blank" rel="nofollow noopener">OpenStreetMap France</a>, sous&nbsp;<a href="http://creativecommons.org/licenses/by-sa/2.0/fr/" target="_blank" rel="nofollow noopener">licence CC BY-SA</a>'`

- `STATICMAP_SUBDOMAINS=a,b,c`

The subdomain will be chosen randomly.

New in version 0.7.23.

The default URL is updated: OpenStreetMap’s tile server no longer requires subdomains.

### API rate limits

New in version 0.7.0.

API rate limits are managed by Flask-Limiter, based on IP with fixed window strategy.
To enable rate limits, Redis must be available.

Note

If no Redis instance is available for rate limits, FitTrackee can still start.
All endpoints are subject to rate limits, except endpoints serving assets.
Limits can be modified by setting the environment variable `API_RATE_LIMITS` (see Flask-Limiter documentation for notation).
Rate limits must be separated by a comma, for instance:

    export API_RATE_LIMITS="200 per day, 50 per hour"

Flask-Limiter provides a Command Line Interface for maintenance and diagnostic purposes.

    $ flask limiter
    Usage: flask limiter [OPTIONS] COMMAND [ARGS]...

      Flask-Limiter maintenance & utility commands

    Options:
      --help  Show this message and exit.

    Commands:
      clear   Clear limits for a specific key
      config  View the extension configuration
      limits  Enumerate details about all routes with rate limits

### Weather data

Changed in version 0.7.11.

The following weather data providers are supported by FitTrackee:

- Visual Crossing (note: historical data are provided on hourly period)

To configure a weather provider, set the following environment variables:

- `WEATHER_API_KEY`: the key to the corresponding weather provider

Changed in version 0.7.15.

DarkSky support is discontinued, since the service shut down on March 31, 2023.

## Installation

Warning

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

### From PyPI

Note

Recommended way on production.

- Create and activate a virtualenv

- Install FitTrackee with pip

    $ pip install fittrackee

- Create `fittrackee` database

Example :

    CREATE USER fittrackee WITH PASSWORD '<PASSWORD>';
    CREATE SCHEMA fittrackee AUTHORIZATION fittrackee;
    CREATE DATABASE fittrackee OWNER fittrackee;

Note

see PostgreSQL documentation for schema and privileges.

- Initialize environment variables, see Environment variables

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

    $ nano .env
    $ source .env

- Initialize database schema

    $ ftcli db upgrade

- Start the application

    $ fittrackee

- Start task queue workers if email sending is enabled, with flask-dramatiq CLI:

    $ flask worker --processes 2

Note

To start application and workers with systemd service, see Deployment

- Open http://localhost:5000 and register

- To set admin rights to the newly created account, use the following command line:

    $ ftcli users update <username> --set-admin true

Note

If the user account is inactive, it activates it.

### From sources

Warning

Since FitTrackee 0.2.1, Python packages installation needs Poetry.
For more information, see Poetry Documentation

Note

To keep virtualenv in project directory, update Poetry configuration.

    $ poetry config virtualenvs.in-project true

#### 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, Vue 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 register

- To set admin rights to the newly created account, use the following command line:

    $ make user-set-admin USERNAME=<username>

Note

If the user account is inactive, it activates it.

#### 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.7.27):

    $ wget https://github.com/SamR1/FitTrackee/archive/v0.7.27.tar.gz
    $ tar -xzf v0.7.27.tar.gz
    $ mv FitTrackee-0.7.27 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

Note

If email sending is disabled: `$ make run-server`

- Open http://localhost:5000 and register

- To set admin rights to the newly created account, use the following command line:

    $ make user-set-admin USERNAME=<username>

Note

If the user account is inactive, it activates it.

## Upgrade

Warning

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

Warning

For now, releases do not follow semantic versioning). Any version may contain backward-incompatible changes.

### From PyPI

- Stop the application and 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 (see changelog for migrations):

    $ ftcli db upgrade

- Restart the application and task queue workers (if email sending is enabled).

### From sources

#### Dev environment

- Stop the application and pull the repository:

    $ git pull

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

- Upgrade packages:

    $ make install-dev

- Upgrade database if needed (see changelog for migrations):

    $ 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.7.27) and overwrite existing files:

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

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

- Upgrade packages:

    $ make install-dev

- Upgrade database if needed (see changelog for migrations):

    $ make upgrade-db

- Restart the server and dramatiq workers:

    $ make run

Note

If email sending is disabled: `$ make run-server`

## 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 adapt depending on your instance configuration and operating system):

- 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="STATICMAP_SUBDOMAINS="
    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

To handle large files, a higher value for timeout can be set.

Note

More information on deployment with Gunicorn in its 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 http2;
        server_name example.com;
        ssl_certificate fullchain.pem;
        ssl_certificate_key privkey.pem;

        ## this parameter controls how large of a file can be
        ## uploaded, and defaults to 1MB. If you change the FitTrackee
        ## settings to allow larger uploads, you'll need to change this
        ## setting by uncommenting the line below and setting the size limit
        ## you want. Set to "0" to prevent nginx from checking the
        ## request body size at all
        # client_max_body_size 1m;

        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;
            proxy_set_header  X-Forwarded-Proto $scheme;
        }
    }

    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:

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

- To initialise database:

    $ make docker-init

- Open http://localhost:5000 and register.

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

- To set admin rights to the newly created account, use the following command line:

    $ make docker-set-admin USERNAME=<username>

Note

If the user account is inactive, it activates it.

- 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

### Development

New in version 0.5.0.

- an additional step is needed to install `fittrackee_client`

    $ make docker-build-client

- to start FitTrackee with client dev tools:

    $ make docker-serve-client

Open http://localhost:3000

Note

Some environment variables need to be updated like `UI_URL`

- to run lint or tests:

    $ make docker-lint-client  # run type check and lint on javascript files
    $ make docker-test-client  # run unit tests on Client
    $ make docker-lint-python  # run type check and lint on python files
    $ make docker-test-python  # run unit tests on API

## Yunohost

A package is available, see https://github.com/YunoHost-Apps/fittrackee_ynh.