Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# 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

- 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 11+

- 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)

    - Node 16+ 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.

Note

Les étapes suivantes décrivent l’installation sur des systèmes Linux (testée sur Debian et Arch).
Sur d’autres systèmes d’exploitations, des problèmes peuvent être rencontrés et des adaptations nécessaires.

## 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:

    `&copy; <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.

VUE_APP_API_URL

  URL de l’API FitTrackee, uniquement pour les environnements de développement.

### 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 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 ThunderForest

- `MAP_ATTRIBUTION=&copy; <a href="http://www.thunderforest.com/">Thunderforest</a>, &copy; <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&nbsp;<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

Méthode recommandée en production.

- 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

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.7.25) :

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

- 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.25) et écraser les fichiers existants :

    $ wget https://github.com/SamR1/FitTrackee/archive/v0.7.25.tar.gz
    $ tar -xzf v0.7.25.tar.gz
    $ cp -R FitTrackee-0.7.25/* 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 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.