Installation¶

FitTrackee peut être installé via un seul paquet Python à partir de PyPI ou à partir des sources après avoir cloné le dépôt.

Dans le cas d’une instance avec un seul utilisateur, il est possible de désactiver l’inscription. Ainsi, seuls Python et PostgreSQL sont nécessaires. Une interface de ligne de commande est disponible pour gérer le compte utilisateur.

Les étapes suivantes décrivent l’installation sur des systèmes Linux (testées sur un système d’exploitation basé sur ArchLinux et sur Ubuntu en intégration continue).

Sur d’autres systèmes d’exploitations, des problèmes peuvent être rencontrés et des adaptations nécessaires.

Note

D’autres guides d’installation sont disponibles grâce aux contributeurs :
- Installation sur l'hébergement web Uberspace (guide en anglais)
- Installation sur Debian 12 net install (guide en allemand)

Dépendances principales¶

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
- gunicorn pour servir l’application
Client :
- Vue3/Vuex
- Leaflet pour afficher la carte
- Chart.js pour afficher les graphiques d’élévation et de vitesse

Le logo, les icônes de certains sports et celles des icônes météo ont été faites par Freepik sur www.flaticon.com.

FitTrackee utilise également les icônes de Fork Awesome.

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 1.2+ (pour l’installation à partir des sources uniquement)
- Node 18+ et Yarn (pour le développement uniquement)
- Docker et Docker Compose (pour le développement ou l’évaluation de l’application)

Note

Si l’inscription des utilisateurs est activé, il est recommandé de configurer un fournisseur SMTP pour l’envoi des courriels et les demandes d’export de données.

Variables d’environnement¶

Avertissement

Depuis la version 0.4.0 de FitTrackee, le fichier 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, sinon fittrackee.

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.

Si True, 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.

Si False, 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

Si l’URL du serveur est invalide, l’envoi des courriels sera désactivé.

L’envoi de courriels avec Office365 peut ne pas fonctionner si l’authentification SMTP est désactivée.

Modifié dans la version 0.5.3.

Les informations d’identification peuvent être omises : smtp://smtp.example.com:25.

Si :<port> est omis, the port par défaut est 25.

Avertissement

Depuis la version 0.6.0, les comptes nouvellement créés doivent être confirmés (un courriel contenant des instructions de confirmation est envoyé après l’inscription).

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 instances 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 ThunderForest
MAP_ATTRIBUTION=© <a href="http://www.thunderforest.com/">Thunderforest</a>, © <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors

Note

Vérifier les conditions d’utilisation du fournisseur de tuiles pour l’attribution des cartes.

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.

La limitation d’accès à l’API est gérée par Flask-Limiter, et basé sur l’adresse IP avec une stratégie de période fixe.

Pour activer la limitation d’accès, Redis doit être accessible.

Note

Si aucune instance Redis n’est disponible, FitTrackee pourra tout de même démarrer.

Tous les points d’accès sont soumis à des limitations d’accès sauf les points servant des assets.
Les limites peuvent être modifiées en configurant la variable API_RATE_LIMITS (cf. la documentation Flask-Limiter sur la notation).
Les limites doivent être séparées par des virgules, par exemple :

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

Remarque : FitTrackee est en cours de développement, certaines fonctionnalités peuvent être instables.

A partir de PyPI¶

Note

Façon la plus simple d’installer FitTrackee

Créer et activer l”environnement virtuel
Installer FitTrackee avec 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

cf. documentation PostgreSQL pour les schémas et privilèges.

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

Pour démarrer l’application et les workers avec le service systemd, cf. Déploiement

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

Depuis la version 0.2.1 de FitTrackee, l’installation des paquets Python nécessite Poetry.

Pour plus d’information, voir la documentation de Poetry

Note

Pour conserver l’environnement virtuel dans le répertoire du projet, mettre à jour la configuration de Poetry.

$ 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

Note : FitTrackee est en cours de développement. Certaines fonctionnalités peuvent être instables.

Télécharger la dernière version (à ce jour, la version v0.8.3) :

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

Avant de procéder à la mise à jour, faire une sauvegarde de l’ensemble des données :
- base de données (avec pg_dump par exemple)
- répertoire des fichiers téléversés (voir Variables d'environnement)

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¶

Avertissement

Seulement si FitTrackee a été installé initialement à 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¶

Avertissement

Seulement si FitTrackee a été installé initialement à 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.8.3) et écraser les fichiers existants :

$ wget https://github.com/SamR1/FitTrackee/archive/v0.8.3.tar.gz
$ tar -xzf v0.8.3.tar.gz
$ cp -R FitTrackee-0.8.3/* FitTrackee/
$ cd FitTrackee

Mettre à jour le fichier .env si nécessaire (cf. Variables d’environnement).
Mettre à jour les paquets :

$ make install-python

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 :

Avertissement

À 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¶

Grâce aux contributeurs, un paquet est disponible, cf. https://github.com/YunoHost-Apps/fittrackee_ynh.