Installation#
Cette application est développée en Python (API) et Typescript (client) :
- API :
Flask
gpxpy pour analyser les fichiers gpx
staticmap pour générer une image de la trace à partir des données du fichier gpx
dramatiq pour la file d’attente des tâches
Authlib pour le support de l’autorisation OAuth 2.0
Flask-Limiter pour les limitations d’accès à l’API
Prérequis#
- obligatoires
Python >= 3.8.1
PostgreSQL 12+
- optionnels
Redis pour la file d’attente de tâches (si l’envoi des courriels est activé et pour les demandes d’export de données) et les limitations d’accès à l’API
Fournisseur SMTP (si l’envoi des courriels est activé)
Clé d’API d’un fournisseur de données météo
Poetry (pour l’installation à partir des sources uniquement)
Docker et Docker Compose (pour le développement ou l’évaluation de l’application)
Note
Note
Variables d’environnement#
Avertissement
Makefile.custom.config
est remplacé par le fichier .env
Les variables d’environnements suivantes sont utilisées par l’application web de FitTrackee ou la librairie de gestion de la file d’attente des tâches. Elles ne sont pas toutes obligatoires selon la méthode de déploiement.
- FLASK_APP#
- Nom du module à importer au démarrage de Flask.
FLASK_APP
doit contenir$(PWD)/fittrackee/__main__.py
dans le cas de l’installation à partir des sources, sinonfittrackee
.
- HOST#
Hôte FitTrackee.
- défaut:
127.0.0.1
- PORT#
Port de l’application web FitTrackee.
- défaut:
5000
- APP_SETTINGS#
Configuration de FitTrackee.
- défaut:
fittrackee.config.ProductionConfig
- APP_SECRET_KEY#
clé secrète de FitTrackee, doit être initialisé sur un environnement de production.
Avertissement
Utiliser une clé secrète forte. Cette clé est utilisée pour la génération des jetons JWT.
- APP_WORKERS#
Nombre de _workers_ lancés par Gunicorn.
- défaut:
1
- APP_LOG#
Nouveau dans la version 0.4.0.
Chemin du fichier log
- UPLOAD_FOLDER#
Nouveau dans la version 0.4.0.
Un chemin absolu vers le répertoire dans le répertoire uploads sera créé.
- défaut:
<application_directory>/fittrackee
Danger
Dans le cas d’une installation avec PyPI, le répertoire sera localisé dans le répertoire de l’environnement virtuel Python si la variable n’est pas initialisée.
- DATABASE_URL#
- URL de la base de données avec le nom et le mot de passe de l’utilisateur, doit être initialisée sur les environnements de production.Exemple pour un environnement de développement :
postgresql://fittrackee:fittrackee@localhost:5432/fittrackee
Avertissement
Depuis la version 1.4+ de SQLAlchemy, l’URL doit commencé avec postgresql://.
- DATABASE_DISABLE_POOLING#
Nouveau dans la version 0.4.0.
Désactiver le pooling si nécessaire (dans le cas du démarrage direct avec le point d’entrée de FitTrackee et non avec Gunicorn), cf. la documentation de SqlAlchemy.
- défaut:
false
- UI_URL#
URL de FitTrackee, nécessaire pour les liens dans les courriels.
- EMAIL_URL#
Nouveau dans la version 0.3.0.
URL du serveur d’envoi des courriels avec les informations de connexion, cf. Courriels.
Modifié dans la version 0.6.5.
- défaut:
chaine de caractère vide
Danger
Si l’URL du serveur est vide, l’envoi des courriels sera désactivé.
Avertissement
Si l’URL du serveur est invalide, l’envoi des courriels sera désactivé.
- SENDER_EMAIL#
Nouveau dans la version 0.3.0.
Adresse électronique de l’expéditeur FitTrackee.
- REDIS_URL#
Nouveau dans la version 0.3.0.
Instance Redis utilisée par Dramatiq et Flask-Limiter.
- défaut:
instance locale Redis (
redis://
)
- WORKERS_PROCESSES#
Nouveau dans la version 0.3.0.
Nombre de processus utilisés par Dramatiq.
- API_RATE_LIMITS#
Nouveau dans la version 0.7.0.
Limite d’accès à l’API, cf. Limitation d’accès à l’API.
- défaut:
300 per 5 minutes
- TILE_SERVER_URL#
Nouveau dans la version 0.4.0.
URl du serveur de tuiles (avec la clé de l’API si nécessaire), cf. Serveur de tuiles.Depuis la version 0.4.9, il est également utiliser pour générer les images statiques des cartes (pour garder le serveur par défaut cf. DEFAULT_STATICMAP)Modifié dans la version 0.7.23.
L’URL par défaut a été mise à jour : le serveur de tuiles OpenStreetMap ne nécessite plus de sous-domaines.- défaut:
https://tile.openstreetmap.org/{z}/{x}/{y}.png
- STATICMAP_SUBDOMAINS#
Nouveau dans la version 0.6.10.
Certains serveurs de tuiles nécessitent un sous-domaine, df. Serveur de tuiles.Par exemple: « a,b,c » pour OSM France.- défaut:
chaine de caractère vide
- MAP_ATTRIBUTION#
Nouveau dans la version 0.4.0.
Attribution de la carte (si une autre serveur de tuile est utilisé), cf. Serveur de tuiles.
- défaut:
© <a href="http://www.openstreetmap.org/copyright" target="_blank" rel="noopener noreferrer">OpenStreetMap</a> contributors
- DEFAULT_STATICMAP#
Nouveau dans la version 0.4.9.
SiTrue
, le serveur de tuile par défaut de staticmap est conservé pour générer les images statiques de cartes (serveur de tuiles OSM depuis la version 0.5.6 de staticmap (celui de Komoot.de avant cette version)).Sinon, le serveur de tuiles configuré dans TILE_SERVER_URL sera utilisé.Modifié dans la version 0.6.10.
Cette variable est maintenant insensible à la casse.SiFalse
, selon le serveur de tuile, les sous-domaines peuvent être obligatoires.- défaut:
False
- WEATHER_API_KEY#
Modifié dans la version 0.4.0: ⚠️ remplace
WEATHER_API
Clé d’API du fournisseur de données météo (non obligatoire), cf.
WEATHER_API_PROVIDER
.
- WEATHER_API_PROVIDER 🆕#
Nouveau dans la version 0.7.11.
Fournisseur de données météo (non obligatoire), cf Données météo.
- VITE_APP_API_URL#
Modifié dans la version 0.7.26: ⚠️ remplace
VUE_APP_API_URL
Courriels#
Nouveau dans la version 0.3.0.
Pour l’envoi des courriels, une valeur valide pour la variable EMAIL_URL
doit être fourni :
avec un SMTP server sans chiffrement :
smtp://username:password@smtp.example.com:25
avec SSL :
smtp://username:password@smtp.example.com:465/?ssl=True
avec STARTTLS :
smtp://username:password@smtp.example.com:587/?tls=True
Avertissement
Modifié dans la version 0.5.3.
smtp://smtp.example.com:25
.:<port>
est omis, the port par défaut est 25.Avertissement
Les courriels envoyés par FitTrackee sont :
instructions pour la confirmation du compte
demande de réinitialisation du mot de passe
changement d’adresse électronique (vers l’ancienne et la nouvelle adresse)
changement de mot de passe
notification lorsqu’une archive d’export de données est prête à être téléchargée (ajouté dans la version 0.7.13)
Modifié dans la version 0.6.5.
Dans le cas des instance avec un seul utilisateur, il est possible de désactiver l’envoi de courriels en laissant la variable EMAIL_URL
vide (dans ce cas il n’est pas nécessaire de lancer les workers de dramatiq).
Une interface de ligne de commande (CLI) est disponible pour activer les comptes, modifier l’adresse électronique et le mot de passe et gérer les demandes d’exports de données.
Modifié dans la version 0.7.24.
Le mot de passe peut être encodé s’il contient des caractères spéciaux. Par exemple avec le mot de passe passwordwith@and&and?
, le mot de passe encodé sera passwordwith%40and%26and%3F
.
Serveur de tuiles#
Nouveau dans la version 0.4.0.
Le serveur de tuiles par défaut est maintenant le serveur standard d”OpenStreetMap (si les variables d’environnements ne sont pas initialisées). Le serveur de tuile peut être changé en modifiant les variables TILE_SERVER_URL
et MAP_ATTRIBUTION
(liste des serveurs de tuiles).
Pour conserver ThunderForest Outdoors, la configuration est :
TILE_SERVER_URL=https://{s}.tile.thunderforest.com/outdoors/{z}/{x}/{y}.png?apikey=XXXX
où XXXX est la clé d’API de ThunderForestMAP_ATTRIBUTION=© <a href="http://www.thunderforest.com/">Thunderforest</a>, © <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors
Note
Modifié dans la version 0.6.10.
Depuis que le serveur de tuiles peut être utilisé pour la génération des images statiques de cartes, certains serveurs nécessitent un sous-domaine.
Par exemple, pour configurer le serveur d'OSM France, les valeurs attendues sont :
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
Le sous-domaine sera choisi de manière aléatoire.
Nouveau dans la version 0.7.23.
L’URL par défaut a été mise à jour : le serveur de tuiles OpenStreetMap ne nécessite plus de sous-domaines.
Limitation d’accès à l’API#
Nouveau dans la version 0.7.0.
Note
API_RATE_LIMITS
(cf. la documentation Flask-Limiter sur la notation).export API_RATE_LIMITS="200 per day, 50 per hour"
Flask-Limiter fournit une Interface de ligne de commande à des fins de maintenance et de diagnostic.
$ 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
Données météo#
Modifié dans la version 0.7.11.
Les fournisseurs de données météo suivants sont pris en charge par FitTrackee :
Visual Crossing (note : les données historiques sont fournies sur une période d’une heure)
Pour configurer un fournisseur de données météo, initialiser les variables d’environnement suivantes :
WEATHER_API_KEY
: clé d’API correspondant au fournisseur de données météo
Modifié dans la version 0.7.15.
Le support de DarkSky est interrompu, depuis l’arrêt du service le 31 Mars 2023.
Installation#
Avertissement
A partir de PyPI#
Note
Créer et activer l’environnement virtuel
Installer FitTrackee à partir de pip
$ pip install fittrackee
Créer la base de données
fittrackee
Exemple :
CREATE USER fittrackee WITH PASSWORD '<PASSWORD>';
CREATE SCHEMA fittrackee AUTHORIZATION fittrackee;
CREATE DATABASE fittrackee OWNER fittrackee;
Note
Initialiser les variables d’environnement, cf. Variables d’environnement
Par exemple, copier et coller le fichier .env
à partir de .env.example
et activer le fichier.
$ nano .env
$ source .env
Initialiser le schéma de la base de données
$ ftcli db upgrade
Démarrer l’application
$ fittrackee
Démarrer les workers de la file d’attente des tâches si l’envoi des courriels est activé, avec l’interface de ligne de commandes de flask-dramatiq :
$ flask worker --processes 2
Note
Ouvrir l’URL http://localhost:5000 avec un navigateur et s’inscrire
Pour donner les droits d’administration au compte nouvellement créé utiliser la ligne de commande suivante :
$ ftcli users update <username> --set-admin true
Note
Si le compte de l’utilisateur est inactif, il sera alors activée.
A partir des sources#
Avertissement
Note
$ poetry config virtualenvs.in-project true
Environnements de développement#
Cloner ce dépôt :
$ git clone https://github.com/SamR1/FitTrackee.git
$ cd FitTrackee
Créer le fichier .env à partir de l’exemple et le mettre à jour (cf. Variables d’environnement).
Installer l’environnement virtuel Python, Vue et tous les paquets nécessaires et initialiser la base de données :
$ make install-dev
$ make install-db
Démarrer le serveur et le client :
$ make serve
Démarrer les workers dramatiq :
$ make run-workers
Ouvrir l’URL http://localhost:3000 avec un navigateur et s’inscrire
Pour donner les droits d’administration au compte nouvellement créé utiliser la ligne de commande suivante :
$ make user-set-admin USERNAME=<username>
Note
Si le compte de l’utilisateur est inactif, il sera alors activée.
Environnements de production#
Avertissement
Télécharger la dernière version (à ce jour, la version v0.7.27) :
$ wget https://github.com/SamR1/FitTrackee/archive/v0.7.27.tar.gz
$ tar -xzf v0.7.27.tar.gz
$ mv FitTrackee-0.7.27 FitTrackee
$ cd FitTrackee
Créer le fichier .env à partir de l’exemple et le mettre à jour (cf. Variables d’environnement).
Installer l’environnement virtuel Python et tous les paquets nécessaires :
$ make install-python
Initialiser la base de données (après avoir mis à jour
db/create.sql
pour changer les informations de connexion à la base de données) :
$ make install-db
Démarrer le serveur et les workers dramatiq :
$ make run
Note
Si l’envoi des courriels est désactivé : $ make run-server
Ouvrir l’URL http://localhost:5000 avec un navigateur et s’inscrire
Pour donner les droits d’administration au compte nouvellement créé utiliser la ligne de commande suivante :
$ make user-set-admin USERNAME=<username>
Note
Si le compte de l’utilisateur est inactif, il sera alors activée.
Mise à jour#
Avertissement
Avertissement
Les versions publiées ne suivent pas la gestion sémantique de version. Toute version peut contenir des changements non rétro-compatibles.
A partir de PyPI#
Stopper l’application et activer l’environnement virtuel
Mettre à jour avec pip
$ pip install -U fittrackee
Mettre à jour les variables d’environnements si nécessaire et les activer
$ nano .env
$ source .env
Mettre à jour la base de données si nécessaire (voir le journal des changements pour les migrations) :
$ ftcli db upgrade
Redémarrer l’application et les workers de la file d’attente des tâches (si l’envoi des courriels est activé).
A partir des sources#
Environnements de développement#
Arrêter l’application et récupérer les derniers changements du dépôt :
$ git pull
Mettre à jour le fichier .env si nécessaire (cf. Variables d’environnement).
Mettre à jour les paquets :
$ make install-dev
Mettre à jour la base de données si nécessaire (voir le journal des changements pour les migrations) :
$ make upgrade-db
Redémarrer le serveur :
$ make serve
Démarrer les workers dramatiq :
$ make run-workers
Environnement de production#
Arrêter l’application
Changer pour le répertoire dans lequel FitTrackee est localisé
Télécharger la dernière version (à ce jour, la version v0.7.27) et écraser les fichiers existants :
$ wget https://github.com/SamR1/FitTrackee/archive/v0.7.27.tar.gz
$ tar -xzf v0.7.27.tar.gz
$ cp -R FitTrackee-0.7.27/* FitTrackee/
$ cd FitTrackee
Mettre à jour le fichier .env si nécessaire (cf. Variables d’environnement).
Mettre à jour les paquets :
$ make install-dev
Mettre à jour la base de données si nécessaire (voir le journal des changements pour les migrations) :
$ make upgrade-db
Redémarrer le serveur et les workers dramatiq :
$ make run
Note
Si l’envoi des courriels est désactivé : $ make run-server
Déploiement#
Il y a plusieurs méthodes pour démarrer et servir l’application web FitTrackee et l’application de gestion de la file d’attente de tâches. Un des moyens est d’utiliser les services systemd et Nginx to proxy passer à Gunicorn.
Exemples (à adapter selon la configuration de votre instance et votre système d’exploitation) :
pour l’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
Pour gérer les fichiers de taille importante, une valeur plus importante pour le timeout peut être configurée.
Note
Plus d’informations sur le déploiement avec Gunicorn dans sa documentation.
pour les workers de la file d’attente :
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
Configuration Nginx :
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
Si besoin, modifier la configuration pour gérer les fichiers de taille importante (cf. client_max_body_size).
Docker#
Installation#
Nouveau dans la version 0.4.4.
A des fins d”évaluation, des fichiers Docker sont disponible, installant FitTrackee à partir des sources.
Pour installer FitTrackee :
$ git clone https://github.com/SamR1/FitTrackee.git
$ cd FitTrackee
$ cp .env.docker .env
$ make docker-build
Pour initialiser la base de données :
$ make docker-init
Ouvrir l’URL http://localhost:5000 avec un navigateur et s’inscrire.
Ouvrir l’URL http://localhost:8025 pour accéder à l’interface de MailHog (outil de test)
Pour donner les droits d’administration au compte nouvellement créé utiliser la ligne de commande suivante :
$ make docker-set-admin USERNAME=<username>
Note
Si le compte de l’utilisateur est inactif, il sera alors activée.
Pour arrêter Fittrackee :
$ make docker-stop
pour démarrer Fittrackee (application et workers dramatiq) :
$ make docker-run-all
Pour lancer le shell dans le container Fittrackee :
$ make docker-shell
Développement#
Nouveau dans la version 0.5.0.
une étape additionnelle est nécessaire pour installer fittrackee_client
$ make docker-build-client
pour démarrer FitTrackee avec les outils de développement client :
$ make docker-serve-client
Ouvrir http://localhost:3000
Note
Certaines variables d’environnement doivent être mise à jour comme UI_URL
pour lancer le lint et les tests :
$ 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#
Un paquet est disponible, cf. https://github.com/YunoHost-Apps/fittrackee_ynh.