Installation¶
This application is written in Python (API) and Javascript (client):
- API:
Flask
gpxpy to parse gpx files
staticmap to generate a static map image from gpx coordinates
python-forecast.io to fetch weather data from Dark Sky (former forecast.io)
dramatiq for task queue
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 (for development only, to start MailHog 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.
-
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 :
postgres://fittrackee:fittrackee@localhost:5432/fittrackee
-
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.
-
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.
- 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
© <a href=”http://www.openstreetmap.org/copyright” target=”_blank” rel=”noopener noreferrer”>OpenStreetMap</a> contributors
-
WEATHER_API_KEY
¶ Changed in version 0.4.0: ⚠️ replaces
WEATHER_API
Dark Sky API key for weather data (not mandatory).
-
REACT_APP_API_URL
¶ FitTrackee API URL, only needed in dev environment.
Deprecated variables¶
-
REACT_APP_GPX_LIMIT_IMPORT
¶ Deprecated since version 0.3.0: now stored in database
Maximum number of gpx file in zip archive.
- Default
10
-
REACT_APP_MAX_SINGLE_FILE_SIZE
¶ Deprecated since version 0.3.0: now stored in database
Maximum size of a gpx or picture file.
- Default
1MB
-
REACT_APP_MAX_ZIP_FILE_SIZE
¶ Deprecated since version 0.3.0: now stored in database
Maximum size of a zip archive.
- Default
10MB
-
REACT_APP_ALLOW_REGISTRATION
¶ Deprecated since version 0.3.0: now stored in database
Allows users to register.
- Default
true
-
REACT_APP_THUNDERFOREST_API_KEY
¶ Deprecated since version 0.4.0: see TILE_SERVER_URL
ThunderForest API key.
Warning
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
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
From PyPI¶
Note
Warning
Installation¶
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
Upgrade database schema
$ fittrackee_upgrade_db
Initialize database
$ fittrackee_init_data
Start the application
$ fittrackee
Start task queue workers
$ fittrackee_worker --processes 2
Note
Upgrade¶
Warning
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
$ fittrackee_upgrade_db
Restart the application and task queue workers.
From sources¶
Warning
$ yay poetry
$ poetry --version
Poetry 1.0.10
# optional
$ poetry config virtualenvs.in-project true
For other OS, see Poetry Documentation
Installation¶
Dev environment¶
Clone this repo:
$ git clone https://github.com/SamR1/FitTrackee.git
$ cd FitTrackee
Create Makefile.custom.config from example and update it (see Environment variables).
Install Python virtualenv, React 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 log in (the email is admin@example.com
and the password mpwoadmin
) or register
Production environment¶
Warning
Download the last release (for now, it is the release v0.4.0):
$ wget https://github.com/SamR1/FitTrackee/archive/v0.4.0.tar.gz
$ tar -xzf v0.4.0.tar.gz
$ mv FitTrackee-0.4.0 FitTrackee
$ cd FitTrackee
Create Makefile.custom.config 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, log in as admin (the email is
admin@example.com
and the password mpwoadmin
) and change the
password
Upgrade¶
Warning
Dev environment¶
Stop the application and pull the repository:
$ git pull
Update .env if needed
Upgrade packages and database:
$ make install-dev
$ make upgrade-db
Restart the server:
$ make serve
Run dramatiq workers:
$ make run-workers
Prod environment¶
Stop the application and pull the repository:
$ git pull
Update Makefile.custom.config if needed
Upgrade packages and database:
$ make install
$ 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
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;
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
More information on Gunicorn documentation
Docker¶
New in version 0.x.x.
For evaluation purposes (at least for now), 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, log in as admin (the email is admin@example.com and the password mpwoadmin) or register.
Open http://localhost:8025 to access MailHog interface (email testing tool)
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