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
Prerequisites#
- mandatory
Python >= 3.8.1
PostgreSQL 11+
- 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)
Docker and Docker Compose (for development or evaluation purposes)
Note
Note
Environment variables#
Warning
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, elsefittrackee
.
- 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 withpostgresql://
.
- 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)- Default:
https://{s}.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:
© <a href="http://www.openstreetmap.org/copyright" target="_blank" rel="noopener noreferrer">OpenStreetMap</a> contributors
- DEFAULT_STATICMAP#
New in version 0.4.9.
IfTrue
, 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.IfFalse
, 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.
- 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
Warning
Changed in version 0.5.3.
smtp://smtp.example.com:25
.:<port>
is omitted, the port defaults to 25.Warning
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.
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 keyMAP_ATTRIBUTION=© <a href="http://www.thunderforest.com/">Thunderforest</a>, © <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors
Note
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 <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.
API rate limits#
New in version 0.7.0.
Note
API_RATE_LIMITS
(see Flask-Limiter documentation for notation).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
From PyPI#
Note
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
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
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
Note
$ 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
Download the last release (for now, it is the release v0.7.22):
$ wget https://github.com/SamR1/FitTrackee/archive/v0.7.22.tar.gz
$ tar -xzf v0.7.22.tar.gz
$ mv FitTrackee-0.7.22 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
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.22) and overwrite existing files:
$ wget https://github.com/SamR1/FitTrackee/archive/v0.7.22.tar.gz
$ tar -xzf v0.7.22.tar.gz
$ cp -R FitTrackee-0.7.22/* 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
Note
Some environment variables need to be updated like UI_URL
to run lint or tests:
$ make docker-lint-client # run 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.