Installation¶

Main dependencies¶

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

  • gunicorn to serve application

• Client:

  • Vue3/Vuex

  • Leaflet to display map

  • Chart.js to display charts with elevation and speed

Prerequisites¶

• mandatory

  • Python 3.9+

  • 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 1.2+ (for installation from sources only)

  • Node 18+ and Yarn (for development only)

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

Environment variables¶

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¶

Added in version 0.4.0.

Path to log file

UPLOAD_FOLDER¶

Added 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¶

Added 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¶

Added 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¶

Added in version 0.3.0.

FitTrackee sender email address.

REDIS_URL¶

Added in version 0.3.0.

Redis instance used by Dramatiq and Flask-Limiter.

Default:

local Redis instance (redis://)

WORKERS_PROCESSES¶

Added in version 0.3.0.

Number of processes used by Dramatiq.

API_RATE_LIMITS¶

Added in version 0.7.0.

API rate limits, see API rate limits.

Default:

300 per 5 minutes

TILE_SERVER_URL¶

Added 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¶

Added 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¶

Added 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¶

Added 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 🆕¶

Added 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¶

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

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)

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.

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¶

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

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.

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

API rate limits¶

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¶

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

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

Installation¶

$ pip install fittrackee

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

$ nano .env
$ source .env

$ ftcli db upgrade

$ fittrackee

$ flask worker --processes 2

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

$ poetry config virtualenvs.in-project true

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

$ make install-dev
$ make install-db

$ make serve

$ make run-workers

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

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

$ make install-python

$ make install-db

$ make run

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

Upgrade¶

$ pip install -U fittrackee

$ nano .env
$ source .env

$ ftcli db upgrade

$ git pull

$ make install-dev

$ make upgrade-db

$ make serve

$ make run-workers

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

$ make install-python

$ make upgrade-db

$ 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:

• 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

• 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;
    }
}

Docker¶

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

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

$ make docker-stop

$ make docker-shell

$ make docker-build-client

$ make docker-serve-client

$ 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¶

Thanks to contributors, a package is available, see https://github.com/YunoHost-Apps/fittrackee_ynh.

NixOS¶

Thanks to contributors, a package is available on NixOS, see https://mynixos.com/nixpkgs/package/fit-trackee.