Installation¶
This application is written in Python (API) and Typescript (client):
Prerequisites¶
Python 3.7+
PostgreSQL database (10+)
SMTP provider and Redis for task queue (if email sending is enabled)
API key from Dark Sky (not mandatory)
Poetry (for installation from sources only)
Yarn (for development only)
Docker and Docker Compose (for development or evaluation purposes)
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:
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.
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.
- 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
- 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.
If True, it keeps using default tile server to generate static maps (Komoot.de tile server).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
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
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 adresses)
password change
Changed in version 0.6.5.
EMAIL_URL
(in this case, no need to start dramatiq workers).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.
Installation¶
Warning
From PyPI¶
Note
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
Initialize database schema
$ ftcli db upgrade
Start the application
$ fittrackee
Start task queue workers if email sending is enabled.
$ fittrackee_worker --processes 2
Note
Open http://localhost:3000 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
$ 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 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.6.12):
$ wget https://github.com/SamR1/FitTrackee/archive/v0.6.12.tar.gz
$ tar -xzf v0.6.12.tar.gz
$ mv FitTrackee-0.6.12 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
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.6.12) and overwrite existing files:
$ wget https://github.com/SamR1/FitTrackee/archive/v0.6.12.tar.gz
$ tar -xzf v0.6.12.tar.gz
$ cp -R FitTrackee-0.6.12/* 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 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="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
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;
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