Installation

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

Logo, 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 and Docker Compose (for development or 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.

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.

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

VUE_APP_API_URL

FitTrackee API URL, only needed in dev environment.

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

New in version 0.5.3.

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

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

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 DATABASE fittrackee;
CREATE USER fittrackee WITH PASSWORD '<PASSWORD>';
GRANT ALL PRIVILEGES ON DATABASE fittrackee TO fittrackee;

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

$ nano .env
$ source .env
  • Initialize database schema

$ fittrackee_upgrade_db
  • Start the application

$ fittrackee
  • Start task queue workers

$ fittrackee_worker --processes 2

Note

To start application and workers with systemd service, see Deployment
  • Open http://localhost:3000 and register

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

$ fittrackee_set_admin <username>

Note

If the user account is inactive, it activates it.

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

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 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.6.0):

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

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

$ make 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)

From PyPI

  • 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):

$ fittrackee_upgrade_db
  • Restart the application and task queue workers.

From sources

Dev environment

  • Stop the application and pull the repository:

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

$ wget https://github.com/SamR1/FitTrackee/archive/v0.6.0.tar.gz
$ tar -xzf v0.6.0.tar.gz
$ cp -R FitTrackee-0.6.0/* FitTrackee/
$ cd FitTrackee
$ make install-dev
  • Upgrade database if needed (see changelog for migrations):

$ 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 http2;
    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 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