Alexander/FitTrackee
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Docs - init i18n

Browse Source
This commit is contained in:
Sam
2023-06-18 15:23:33 +02:00
parent fe7fbb52e9
commit bf1e12f35d
204 changed files with 41338 additions and 349 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
docs/en/_sources/api/auth.rst.txt Normal file
View File

@ -0,0 +1,25 @@
Authentication and account
##########################
.. autoflask:: fittrackee:create_app()
:endpoints:
auth.register_user,
auth.confirm_account,
auth.resend_account_confirmation_email,
auth.login_user,
auth.get_authenticated_user_profile,
auth.edit_user,
auth.edit_user_preferences,
auth.edit_user_sport_preferences,
auth.reset_user_sport_preferences,
auth.edit_picture,
auth.del_picture,
auth.request_password_reset,
auth.update_user_account,
auth.update_password,
auth.update_email,
auth.logout_user,
auth.accept_privacy_policy,
auth.get_user_data_export,
auth.request_user_data_export,
auth.download_data_export

8
docs/en/_sources/api/configuration.rst.txt Normal file
View File

@ -0,0 +1,8 @@
Configuration
#############
.. autoflask:: fittrackee:create_app()
:endpoints:
config.get_application_config,
config.update_application_config,
config.health_check

15
docs/en/_sources/api/index.rst.txt Normal file
View File

@ -0,0 +1,15 @@
API documentation
#################
.. toctree::
:maxdepth: 2
:caption: Endpoints:
auth
configuration
oauth2
records
sports
stats
users
workouts

14
docs/en/_sources/api/oauth2.rst.txt Normal file
View File

@ -0,0 +1,14 @@
OAuth2
######
.. autoflask:: fittrackee:create_app()
:endpoints:
oauth2.get_clients,
oauth2.create_client,
oauth2.get_client_by_client_id,
oauth2.get_client_by_id,
oauth2.delete_client,
oauth2.revoke_client_tokens,
oauth2.authorize,
oauth2.issue_token,
oauth2.revoke_token

6
docs/en/_sources/api/records.rst.txt Normal file
View File

@ -0,0 +1,6 @@
Records
#######
.. autoflask:: fittrackee:create_app()
:endpoints:
records.get_records

8
docs/en/_sources/api/sports.rst.txt Normal file
View File

@ -0,0 +1,8 @@
Sports
######
.. autoflask:: fittrackee:create_app()
:endpoints:
sports.get_sports,
sports.get_sport,
sports.update_sport

8
docs/en/_sources/api/stats.rst.txt Normal file
View File

@ -0,0 +1,8 @@
Statistics
##########
.. autoflask:: fittrackee:create_app()
:endpoints:
stats.get_workouts_by_time,
stats.get_workouts_by_sport,
stats.get_application_stats

10
docs/en/_sources/api/users.rst.txt Normal file
View File

@ -0,0 +1,10 @@
Users
#####
.. autoflask:: fittrackee:create_app()
:endpoints:
users.get_users,
users.get_single_user,
users.get_picture,
users.update_user,
users.delete_user

18
docs/en/_sources/api/workouts.rst.txt Normal file
View File

@ -0,0 +1,18 @@
Workouts
##########
.. autoflask:: fittrackee:create_app()
:endpoints:
workouts.get_workouts,
workouts.get_workout,
workouts.get_workout_gpx,
workouts.get_workout_chart_data,
workouts.get_segment_chart_data,
workouts.get_segment_gpx,
workouts.get_map,
workouts.get_map_tile,
workouts.download_workout_gpx,
workouts.post_workout,
workouts.post_workout_no_gpx,
workouts.update_workout,
workouts.delete_workout

1051
docs/en/_sources/changelog.md.txt Normal file
View File

File diff suppressed because it is too large Load Diff

170
docs/en/_sources/cli.rst.txt Normal file
View File

@ -0,0 +1,170 @@
Command line interface
######################
A command line interface (CLI) is available to manage database, OAuth2 tokens and users.
.. code-block:: bash
$ ftcli
Usage: ftcli [OPTIONS] COMMAND [ARGS]...
FitTrackee Command Line Interface
Options:
--help Show this message and exit.
Commands:
db Manage database.
oauth2 Manage OAuth2 tokens.
users Manage users.
.. warning::
| The following commands are now deprecated and will be removed in a next version:
| - ``fittrackee_set_admin``
| - ``fittrackee_upgrade_db``
| - ``fittrackee_worker`` (disabled)
Database
~~~~~~~~
``ftcli db drop``
"""""""""""""""""
.. versionadded:: 0.6.5
Empty database and delete uploaded files, only on development environments.
``ftcli db upgrade``
""""""""""""""""""""
.. versionadded:: 0.6.5
Apply migrations.
OAuth2
~~~~~~
``ftcli oauth2 clean``
""""""""""""""""""""""
.. versionadded:: 0.7.0
Remove tokens expired for more than provided number of days
.. cssclass:: table-bordered
.. list-table::
:widths: 25 50
:header-rows: 1
* - Options
- Description
* - ``--days``
- Number of days.
Users
~~~~~
``ftcli users clean_archives``
""""""""""""""""""""""""""""""
.. versionadded:: 0.7.13
Delete export requests and related archives created more than provided number of days.
.. cssclass:: table-bordered
.. list-table::
:widths: 25 50
:header-rows: 1
* - Options
- Description
* - ``--days``
- Number of days.
``ftcli users clean_tokens``
""""""""""""""""""""""""""""
.. versionadded:: 0.7.0
Remove blacklisted tokens expired for more than provided number of days.
.. cssclass:: table-bordered
.. list-table::
:widths: 25 50
:header-rows: 1
* - Options
- Description
* - ``--days``
- Number of days.
``ftcli users create``
""""""""""""""""""""""
.. versionadded:: 0.7.15
Create a user account.
.. note::
- the newly created account is already active.
- the CLI allows to create users when registration is disabled.
.. cssclass:: table-bordered
.. list-table::
:widths: 25 50
:header-rows: 1
* - Arguments/options
- Description
* - ``USERNAME``
- Username.
* - ``--email EMAIL``
- User email (mandatory).
* - ``--password PASSWORD``
- User password (if not provided, a random password is generated).
``ftcli users export_archives``
"""""""""""""""""""""""""""""""
.. versionadded:: 0.7.13
Process incomplete user export requests.
Can be used if redis is not set (no dramatiq workers running).
.. cssclass:: table-bordered
.. list-table::
:widths: 25 50
:header-rows: 1
* - Options
- Description
* - ``--max``
- Maximum number of export requests to process.
``ftcli users update``
""""""""""""""""""""""
.. versionadded:: 0.6.5
Modify a user account (admin rights, active status, email and password).
.. cssclass:: table-bordered
.. list-table::
:widths: 25 50
:header-rows: 1
* - Arguments/options
- Description
* - ``USERNAME``
- Username.
* - ``--set-admin BOOLEAN``
- Add/remove admin rights (when adding admin rights, it also activates user account if not active).
* - ``--activate``
- Activate user account.
* - ``--reset-password``
- Reset user password (a new password will be displayed).
* - ``--update-email EMAIL``
- Update user email.

246
docs/en/_sources/features.rst.txt Normal file
View File

@ -0,0 +1,246 @@
Features
########
| **FitTrackee** allows you to store and display gpx files and some statistics from your outdoor activities.
| For now, this app is kind of a single-user application. Even if several users can register, a user can only view his own workouts.
Gpx files are stored in an upload directory (without encryption).
With the default configuration, `Open Street Map <https://www.openstreetmap.org>`__ is used as tile server in Workout detail and for static map generation.
Workouts
^^^^^^^^
- 14 sports are supported:
- Cycling (Sport)
- Cycling (Transport)
- Cycling (Virtual) (*new in 0.7.3*)
- Hiking
- Mountain Biking
- Mountain Biking (Electric) (*new in 0.5.0*)
- Mountaineering (*new in 0.7.9*)
- Rowing (*new in 0.5.0*)
- Running
- Skiing (Alpine) (*new in 0.5.0*)
- Skiing (Cross Country) (*new in 0.5.0*)
- Snowshoes (*new in 0.5.2*)
- Trail (*new in 0.5.0*)
- Walking
- (*new in 0.5.0*) Stopped speed threshold used by `gpxpy <https://github.com/tkrajina/gpxpy>`_ is not the default one for the following sports (0.1 km/h instead of 1 km/h):
- Hiking
- Mountaineering
- Skiing (Cross Country)
- Snowshoes
- Trail
- Walking
.. note::
It can be overridden in user preferences.
- Dashboard with month calendar displaying workouts and record. The week can start on Sunday or Monday (which can be changed in the user preferences). The calendar displays up to 100 workouts.
- Workout creation by uploading a gpx file (related data are stored in database in metric system).
.. note::
| Only gpx files with time are supported.
| Calculated values may differ from values calculated by the application that originally generated the gpx files, in particular the maximum speed.
- | A workout can even be created without gpx (the user must enter date, time, duration and distance).
| Ascent and descent can also be provided (*new in 0.7.10*).
- | A workout with a gpx file can be displayed with map and charts (speed and elevation).
| Controls allow full screen view and position reset (*new in 0.5.5*).
- | If **Visual Crossing** (*new in 0.7.11*) API key is provided, weather is displayed in workout detail. Data source is displayed in **About** page.
| Wind is displayed, with an arrow indicating the direction (a tooltip can be displayed with the direction that the wind is coming **from**) (*new in 0.5.5*).
- Segments can be displayed.
- Workout gpx file can be downloaded (*new in 0.5.1*)
- Workout edition and deletion. User can add a note.
- User statistics, by time period (week, month, year) and sport:
- total distance
- total duration
- total workouts
- total ascent (*new in 0.5.0*)
- total descent (*new in 0.5.0*)
- average speed (*new in 0.5.1*)
- User records by sports:
- average speed
- farthest distance
- highest ascent (*new in 0.6.11*, can be hidden, see user preferences)
- longest duration
- maximum speed
.. note::
Records may differ from records displayed by the application that originally generated the gpx files.
- Workouts list.
- The user can filter workouts on:
- date
- sports (only sports with workouts are displayed in sport dropdown)
- title (*new in 0.7.15*)
- distance
- duration
- average speed
- maximum speed
- Workouts can be sorted by:
- date
- distance
- duration
- average speed
.. note::
For now, only the owner of the workout can see it.
Account & preferences
^^^^^^^^^^^^^^^^^^^^^
- A user can create, update and deleted his account.
- The user must agree to the privacy policy to register. If a more recent policy is available, a message is displayed on the dashboard to review the new version (*new in 0.7.13*).
- On registration, the user account is created with selected language in dropdown as user preference (*new in 0.6.9*).
- After registration, the user account is inactive and an email with confirmation instructions is sent to activate it.
A user with an inactive account cannot log in. (*new in 0.6.0*).
.. note::
In case email sending is not configured, a `command line <cli.html#ftcli-users-update>`__ allows to activate users account.
- A user can set language, timezone and first day of week.
- A user can reset his password (*new in 0.3.0*)
- A user can change his email address (*new in 0.6.0*)
- A user can choose between metric system and imperial system for distance, elevation and speed display (*new in 0.5.0*)
- A user can choose to display or hide ascent records and total on Dashboard (*new in 0.6.11*)
- A user can choose format used to display dates (*new in 0.7.3*)
- A user can choose elevation chart axis start: zero or minimum altitude (*new in 0.7.15*)
- A user can choose to exclude extreme values (which may be GPS errors) when calculating the maximum speed (by default, extreme values are excluded) (*new in 0.7.16*)
.. note::
Changing this preference will only affect next file uploads.
- A user can set sport preferences (*new in 0.5.0*):
- change sport color (used for sport image and charts)
- can override stopped speed threshold (for next uploaded gpx files)
- disable/enable a sport.
.. note::
| If a sport is disabled by an administrator, it can not be enabled by a user. In this case, it will only appear in preferences if the user has workouts and only sport color can be changed.
| A disabled sport (by admin or user) will not appear in dropdown when **adding a workout**.
| A workout with a disabled sport will still be displayed in the application.
- A user can create `clients <apps.html>`__ for third-party applications (*new in 0.7.0*).
- | A user can request a data export (*new in 0.7.13*).
| It generates a zip archive containing 2 ``json`` files (user info and workouts data) and all uploaded gpx files.
.. note::
For now, it's not possible to import these files into another **FitTrackee** instance.
Administration
^^^^^^^^^^^^^^
(*new in 0.3.0*)
Application
"""""""""""
**Configuration**
The following parameters can be set:
- active users limit. If 0, registration is enabled (no limit defined).
- maximum size of gpx file (individually uploaded or in a zip archive) (*changed in 0.7.4*)
- maximum size of zip archive
- maximum number of files in the zip archive (*changed in 0.7.4*)
- administrator email for contact (*new in 0.6.0*)
.. warning::
Updating server configuration may be necessary to handle large files (like `nginx <https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size>`_ for instance).
.. note::
If email sending is disabled, a warning is displayed.
**About**
(*new in 0.7.13*)
| It is possible displayed additional information that may be useful to users in **About** page.
| Markdown syntax can be used.
**Privacy policy**
(*new in 0.7.13*)
| A default privacy policy is available (originally adapted from the `Discourse <https://github.com/discourse/discourse>`__ privacy policy).
| A custom privacy policy can set if needed (Markdown syntax can be used). A policy update will display a message on users dashboard to review it.
.. note::
Only the default privacy policy is translated (if the translation is available).
Users
"""""
- display and filter users list
- edit a user to:
- add/remove administration rights
- activate his account (*new in 0.6.0*)
- update his email (in case his account is locked) (*new in 0.6.0*)
- reset his password (in case his account is locked) (*new in 0.6.0*). If email sending is disabled, it is only possible via CLI.
- delete a user
Sports
""""""
- enable or disable a sport (a sport can be disabled even if workout with this sport exists)
Translations
^^^^^^^^^^^^
FitTrackee is available in the following languages (which can be saved in the user preferences):
- English
- French (*new in 0.2.3*)
- German (*new in 0.6.9*)
- Dutch (*new in 0.7.8*)
- Italian (*new in 0.7.10*)
- Galician (*new in 0.7.15*)
- Spanish (*new in 0.7.15*)
- Norwegian Bokmål (*new in 0.7.15*)
Translations status on `Weblate <https://hosted.weblate.org/engage/fittrackee/>`__ (may differ from the released version):
.. figure:: https://hosted.weblate.org/widgets/fittrackee/-/multi-auto.svg
.. note::
Polish is not yet available in **FitTrackee** interface.
Screenshots
^^^^^^^^^^^^
Dashboard
"""""""""
.. figure:: _images/fittrackee_screenshot-01.png
:alt: FitTrackee Dashboard
Workout detail
""""""""""""""
.. figure:: _images/fittrackee_screenshot-02.png
:alt: FitTrackee Workout
Workouts list
"""""""""""""
.. figure:: _images/fittrackee_screenshot-03.png
:alt: FitTrackee Workouts
Statistics
""""""""""
.. figure:: _images/fittrackee_screenshot-04.png
:alt: FitTrackee Statistics
Administration
""""""""""""""
.. figure:: _images/fittrackee_screenshot-05.png
:alt: FitTrackee Administration
.. figure:: _images/fittrackee_screenshot-06.png
:alt: FitTrackee Sports Administration

42
docs/en/_sources/index.rst.txt Normal file
View File

@ -0,0 +1,42 @@
.. FitTrackee documentation master file, created by
sphinx-quickstart on Sun Jul 14 14:43:43 2019.
FitTrackee
==========
| This web application allows you to track your outdoor activities (workouts)
from gpx files and keep your data on your own server.
| No mobile app has been developed yet, but several existing mobile apps can
store workouts data locally and export them into a gpx file.
| Examples for Android (non-exhaustive list):
| \* `Runner Up <https://github.com/jonasoreland/runnerup>`_ (GPL v3)
| \* `ForRunners <https://gitlab.com/brvier/ForRunners>`_ (GPL v3)
| \* `OpenTracks <https://github.com/OpenTracksApp/OpenTracks>`_ (Apache License)
| \* `FitoTrack <https://codeberg.org/jannis/FitoTrack>`_ (GPL v3)
| Maps are displayed using `Open Street
Map <https://www.openstreetmap.org>`__.
| It is also possible to add a workout without a gpx file.
| **Still under heavy development (some features may be unstable).**
| (see `issues <https://github.com/SamR1/FitTrackee/issues>`__ for more information)
.. figure:: _images/fittrackee_screenshot-01.png
:alt: FitTrackee Dashboard
Table of contents
=================
.. toctree::
:maxdepth: 1
features
oauth
installation
cli
third_party_tools
api/index
troubleshooting/index
changelog

889
docs/en/_sources/installation.rst.txt Normal file
View File

@ -0,0 +1,889 @@
Installation
############
This application is written in Python (API) and Typescript (client):
- API:
- Flask
- `gpxpy <https://github.com/tkrajina/gpxpy>`_ to parse gpx files
- `staticmap <https://github.com/komoot/staticmap>`_ to generate a static map image from gpx coordinates
- `dramatiq <https://flask-dramatiq.readthedocs.io/en/latest/>`_ for task queue
- `Authlib <https://docs.authlib.org/en/latest/>`_ for OAuth 2.0 Authorization support
- `Flask-Limiter <https://flask-limiter.readthedocs.io/en/stable>`_ for API rate limits
- Client:
- Vue3/Vuex
- `Leaflet <https://leafletjs.com/>`__ to display map
- `Chart.js <https://www.chartjs.org/>`__ to display charts with elevation and speed
| Logo, some sports and weather icons are made by `Freepik <https://www.freepik.com/>`__ from `www.flaticon.com <https://www.flaticon.com/>`__.
| FitTrackee also uses icons from `Fork Awesome <https://forkaweso.me>`__.
Prerequisites
~~~~~~~~~~~~~
- mandatory
- Python 3.8+
- PostgreSQL 11+
- optional
- Redis for task queue (if email sending is enabled and for data export requests) and API rate limits
- SMTP provider (if email sending is enabled)
- API key from a `weather data provider <installation.html#weather-data>`__
- `Poetry <https://poetry.eustace.io>`__ (for installation from sources only)
- `Node <https://nodejs.org>`__ 16+ and `Yarn <https://yarnpkg.com>`__ (for development only)
- Docker and Docker Compose (for development or evaluation purposes)
.. note::
| If registration is enabled, it is recommended to set Redis and a SMTP provider for email sending and data export requests.
.. note::
| The following steps describe an installation on Linux systems (tested
on Debian and Arch).
| On other OS, some issues can be encountered and adaptations may be
necessary.
Environment variables
~~~~~~~~~~~~~~~~~~~~~
.. warning::
| Since FitTrackee 0.4.0, ``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.
.. envvar:: FLASK_APP
| Name of the module to import at flask run.
| ``FLASK_APP`` should contain ``$(PWD)/fittrackee/__main__.py`` with installation from sources, else ``fittrackee``.
.. envvar:: HOST
**FitTrackee** host.
:default: 127.0.0.1
.. envvar:: PORT
**FitTrackee** port.
:default: 5000
.. envvar:: APP_SETTINGS
**FitTrackee** configuration.
:default: fittrackee.config.ProductionConfig
.. envvar:: 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.
.. envvar:: APP_WORKERS
Number of workers spawned by **Gunicorn**.
:default: 1
.. envvar:: APP_LOG
.. versionadded:: 0.4.0
Path to log file
.. envvar:: UPLOAD_FOLDER
.. versionadded:: 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.
.. envvar:: 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+) <https://docs.sqlalchemy.org/en/14/changelog/changelog_14.html#change-3687655465c25a39b968b4f5f6e9170b>`__,
engine URL should begin with ``postgresql://``.
.. envvar:: DATABASE_DISABLE_POOLING
.. versionadded:: 0.4.0
Disable pooling if needed (when starting application with **FitTrackee** entry point and not directly with **Gunicorn**),
see `SqlAlchemy documentation <https://docs.sqlalchemy.org/en/13/core/pooling.html#using-connection-pools-with-multiprocessing-or-os-fork>`__.
:default: ``false``
.. envvar:: UI_URL
**FitTrackee** URL, needed for links in emails.
.. envvar:: EMAIL_URL
.. versionadded:: 0.3.0
Email URL with credentials, see `Emails <installation.html#emails>`__.
.. versionchanged:: 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.
.. envvar:: SENDER_EMAIL
.. versionadded:: 0.3.0
**FitTrackee** sender email address.
.. envvar:: REDIS_URL
.. versionadded:: 0.3.0
Redis instance used by **Dramatiq** and **Flask-Limiter**.
:default: local Redis instance (``redis://``)
.. envvar:: WORKERS_PROCESSES
.. versionadded:: 0.3.0
Number of processes used by **Dramatiq**.
.. envvar:: API_RATE_LIMITS
.. versionadded:: 0.7.0
API rate limits, see `API rate limits <installation.html#api-rate-limits>`__.
:default: ``300 per 5 minutes``
.. envvar:: TILE_SERVER_URL
.. versionadded:: 0.4.0
| Tile server URL (with api key if needed), see `Map tile server <installation.html#map-tile-server>`__.
| Since **0.4.9**, it's also used to generate static maps (to keep default server, see `DEFAULT_STATICMAP <installation.html#envvar-DEFAULT_STATICMAP>`__)
:default: ``https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png``
.. envvar:: STATICMAP_SUBDOMAINS
.. versionadded:: 0.6.10
| Some tile servers require a subdomain, see `Map tile server <installation.html#map-tile-server>`__.
| For instance: "a,b,c" for OSM France.
:default: empty string
.. envvar:: MAP_ATTRIBUTION
.. versionadded:: 0.4.0
Map attribution (if using another tile server), see `Map tile server <installation.html#map-tile-server>`__.
:default: ``&copy; <a href="http://www.openstreetmap.org/copyright" target="_blank" rel="noopener noreferrer">OpenStreetMap</a> contributors``
.. envvar:: DEFAULT_STATICMAP
.. versionadded:: 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 <installation.html#envvar-TILE_SERVER_URL>`__.
.. versionchanged:: 0.6.10
| This variable is now case-insensitive.
| If ``False``, depending on tile server, `subdomains <installation.html#envvar-STATICMAP_SUBDOMAINS>`__ may be mandatory.
:default: False
.. envvar:: WEATHER_API_KEY
.. versionchanged:: 0.4.0 ⚠️ replaces ``WEATHER_API``
Weather API key (not mandatory), see ``WEATHER_API_PROVIDER``.
.. envvar:: WEATHER_API_PROVIDER 🆕
.. versionadded:: 0.7.11
Provider for weather data (not mandatory), see `Weather data <installation.html#weather-data>`__.
.. envvar:: VUE_APP_API_URL
**FitTrackee** API URL, only needed in dev environment.
Emails
^^^^^^
.. versionadded:: 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::
| - If the email URL is invalid, the application may not start.
| - Sending emails with Office365 may not work if SMTP auth is disabled.
.. versionchanged:: 0.5.3
| Credentials can be omitted: ``smtp://smtp.example.com:25``.
| If ``:<port>`` is omitted, the port defaults to 25.
.. warning::
| Since 0.6.0, newly created accounts must be confirmed (an email with confirmation instructions is sent after registration).
Emails sent by FitTrackee are:
- account confirmation instructions
- password reset request
- email change (to old and new email adresses)
- password change
- notification when a data export archive is ready to download (*new in 0.7.13*)
.. versionchanged:: 0.6.5
For single-user instance, it is possible to disable email sending with an empty ``EMAIL_URL`` (in this case, no need to start dramatiq workers).
A `CLI <cli.html#ftcli-users-update>`__ is available to activate account, modify email and password and handle data export requests.
Map tile server
^^^^^^^^^^^^^^^
.. versionadded:: 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 <https://wiki.openstreetmap.org/wiki/Raster_tile_providers>`__).
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 key
- ``MAP_ATTRIBUTION=&copy; <a href="http://www.thunderforest.com/">Thunderforest</a>, &copy; <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors``
.. note::
| Check the terms of service of tile provider for map attribution.
.. versionchanged:: 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&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``
The subdomain will be chosen randomly.
API rate limits
^^^^^^^^^^^^^^^
.. versionadded:: 0.7.0
| API rate limits are managed by `Flask-Limiter <https://flask-limiter.readthedocs.io/en/stable>`_, based on IP with fixed window strategy.
| To enable rate limits, **Redis** must be available.
.. note::
| If no Redis instance is available for rate limits, FitTrackee can still start.
| All endpoints are subject to rate limits, except endpoints serving assets.
| Limits can be modified by setting the environment variable ``API_RATE_LIMITS`` (see `Flask-Limiter documentation for notation <https://flask-limiter.readthedocs.io/en/stable/configuration.html#rate-limit-string-notation>`_).
| Rate limits must be separated by a comma, for instance:
.. code-block::
export API_RATE_LIMITS="200 per day, 50 per hour"
**Flask-Limiter** provides a `Command Line Interface <https://flask-limiter.readthedocs.io/en/stable/cli.html>`_ for maintenance and diagnostic purposes.
.. code-block:: bash
$ flask limiter
Usage: flask limiter [OPTIONS] COMMAND [ARGS]...
Flask-Limiter maintenance & utility commmands
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
Weather data
^^^^^^^^^^^^
.. versionchanged:: 0.7.11
The following weather data providers are supported by **FitTrackee**:
- `Visual Crossing <https://www.visualcrossing.com>`__ (**note**: historical data are provided on hourly period)
To configure a weather provider, set the following environment variables:
- ``WEATHER_API_KEY``: the key to the corresponding weather provider
.. versionchanged:: 0.7.15
**DarkSky** support is discontinued, since the service shut down on March 31, 2023.
Installation
~~~~~~~~~~~~
.. warning::
| Note that **FitTrackee** is under heavy development, some features may be unstable.
From PyPI
^^^^^^^^^
.. note::
| Recommended way on production.
- Create and activate a virtualenv
- Install **FitTrackee** with pip
.. code-block:: bash
$ pip install fittrackee
- Create ``fittrackee`` database
Example :
.. code-block:: sql
CREATE USER fittrackee WITH PASSWORD '<PASSWORD>';
CREATE SCHEMA fittrackee AUTHORIZATION fittrackee;
CREATE DATABASE fittrackee OWNER fittrackee;
.. note::
| see PostgreSQL `documentation <https://www.postgresql.org/docs/15/ddl-schemas.html>`_ for schema and privileges.
- Initialize environment variables, see `Environment variables <installation.html#environment-variables>`__
For instance, copy and update ``.env`` file from ``.env.example`` and source the file.
.. code-block:: bash
$ nano .env
$ source .env
- Initialize database schema
.. code-block:: bash
$ ftcli db upgrade
- Start the application
.. code-block:: bash
$ fittrackee
- Start task queue workers if email sending is enabled, with flask-dramatiq CLI:
.. code-block:: bash
$ flask worker --processes 2
.. note::
| To start application and workers with **systemd** service, see `Deployment <installation.html#deployment>`__
- Open http://localhost:5000 and register
- To set admin rights to the newly created account, use the following command line:
.. code:: bash
$ ftcli users update <username> --set-admin true
.. note::
If the user account is inactive, it activates it.
From sources
^^^^^^^^^^^^
.. warning::
| Since **FitTrackee** 0.2.1, Python packages installation needs Poetry.
| For more information, see `Poetry Documentation <https://python-poetry.org/docs/#installation>`__
.. note::
| To keep virtualenv in project directory, update Poetry configuration.
.. code-block:: bash
$ poetry config virtualenvs.in-project true
Dev environment
"""""""""""""""
- Clone this repo:
.. code:: bash
$ git clone https://github.com/SamR1/FitTrackee.git
$ cd FitTrackee
- Create **.env** from example and update it
(see `Environment variables <installation.html#environment-variables>`__).
- Install Python virtualenv, Vue and all related packages and
initialize the database:
.. code:: bash
$ make install-dev
$ make install-db
- Start the server and the client:
.. code:: bash
$ make serve
- Run dramatiq workers:
.. code:: bash
$ make run-workers
- Open http://localhost:3000 and register
- To set admin rights to the newly created account, use the following command line:
.. code:: bash
$ make user-set-admin USERNAME=<username>
.. note::
If the user account is inactive, it activates it.
Production environment
""""""""""""""""""""""
.. warning::
| Note that FitTrackee is under heavy development, some features may be unstable.
- Download the last release (for now, it is the release v0.7.17):
.. code:: bash
$ wget https://github.com/SamR1/FitTrackee/archive/v0.7.17.tar.gz
$ tar -xzf v0.7.17.tar.gz
$ mv FitTrackee-0.7.17 FitTrackee
$ cd FitTrackee
- Create **.env** from example and update it
(see `Environment variables <installation.html#environment-variables>`__).
- Install Python virtualenv and all related packages:
.. code:: bash
$ make install-python
- Initialize the database (**after updating** ``db/create.sql`` **to change
database credentials**):
.. code:: bash
$ make install-db
- Start the server and dramatiq workers:
.. code:: bash
$ 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:
.. code:: bash
$ make user-set-admin USERNAME=<username>
.. note::
If the user account is inactive, it activates it.
Upgrade
~~~~~~~
.. warning::
| Before upgrading, make a backup of all data:
| - database (with `pg_dump <https://www.postgresql.org/docs/11/app-pgdump.html>`__ for instance)
| - upload directory (see `Environment variables <installation.html#environment-variables>`__)
From PyPI
^^^^^^^^^
- Stop the application and activate the virtualenv
- Upgrade with pip
.. code-block:: bash
$ pip install -U fittrackee
- Update environment variables if needed and source environment variables file
.. code-block:: bash
$ nano .env
$ source .env
- Upgrade database if needed (see changelog for migrations):
.. code-block:: bash
$ 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:
.. code:: bash
$ git pull
- Update **.env** if needed (see `Environment variables <installation.html#environment-variables>`__).
- Upgrade packages:
.. code:: bash
$ make install-dev
- Upgrade database if needed (see changelog for migrations):
.. code:: bash
$ make upgrade-db
- Restart the server:
.. code:: bash
$ make serve
- Run dramatiq workers:
.. code:: bash
$ 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.7.17) and overwrite existing files:
.. code:: bash
$ wget https://github.com/SamR1/FitTrackee/archive/v0.7.17.tar.gz
$ tar -xzf v0.7.17.tar.gz
$ cp -R FitTrackee-0.7.17/* FitTrackee/
$ cd FitTrackee
- Update **.env** if needed (see `Environment variables <installation.html#environment-variables>`__).
- Upgrade packages:
.. code:: bash
$ make install-dev
- Upgrade database if needed (see changelog for migrations):
.. code:: bash
$ make upgrade-db
- Restart the server and dramatiq workers:
.. code:: bash
$ 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 adapt depending on your instance configuration and operating system):
- for application: ``fittrackee.service``
.. code-block::
[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::
To handle large files, a higher value for `timeout <https://docs.gunicorn.org/en/stable/settings.html#timeout>`__ can be set.
.. note::
More information on deployment with Gunicorn in its `documentation <https://docs.gunicorn.org/en/stable/deploy.html>`__.
- for task queue workers: ``fittrackee_workers.service``
.. code-block::
[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:
.. code-block::
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::
If needed, update configuration to handle larger files (see `client_max_body_size <https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size>`_).
Docker
~~~~~~
Installation
^^^^^^^^^^^^
.. versionadded:: 0.4.4
For evaluation purposes, docker files are available, installing **FitTrackee** from **sources**.
- To install **FitTrackee**:
.. code-block:: bash
$ git clone https://github.com/SamR1/FitTrackee.git
$ cd FitTrackee
$ cp .env.docker .env
$ make docker-build
- To initialise database:
.. code-block:: bash
$ make docker-init
- Open http://localhost:5000 and register.
Open http://localhost:8025 to access `MailHog interface <https://github.com/mailhog/MailHog>`_ (email testing tool)
- To set admin rights to the newly created account, use the following command line:
.. code:: bash
$ make docker-set-admin USERNAME=<username>
.. note::
If the user account is inactive, it activates it.
- To stop **Fittrackee**:
.. code-block:: bash
$ make docker-stop
- To start **Fittrackee** (application and dramatiq workers):
.. code-block:: bash
$ make docker-run-all
- To run shell inside **Fittrackee** container:
.. code-block:: bash
$ make docker-shell
Development
^^^^^^^^^^^
.. versionadded:: 0.5.0
- an additional step is needed to install ``fittrackee_client``
.. code-block:: bash
$ make docker-build-client
- to start **FitTrackee** with client dev tools:
.. code-block:: bash
$ make docker-serve-client
Open http://localhost:3000
.. note::
Some environment variables need to be updated like ``UI_URL``
- to run lint or tests:
.. code-block:: bash
$ 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
~~~~~~~~
A package is available, see https://github.com/YunoHost-Apps/fittrackee_ynh.

97
docs/en/_sources/oauth.rst.txt Normal file
View File

@ -0,0 +1,97 @@
OAuth 2.0
#########
(*new in 0.7.0*)
FitTrackee provides a REST API (see `documentation <api/index.html>`__) whose
most endpoints require authentication/authorization.
To allow a third-party application to interact with API endpoints, an
`OAuth2 <https://datatracker.ietf.org/doc/html/rfc6749>`_ client can be created
in user settings ('apps' tab).
.. warning::
OAuth2 endpoints requiring authentication are not accessible by third-party
applications (`documentation <api/oauth2.html>`__), only by FitTrackee
client (first-party application).
FitTrackee supports only `Authorization Code <https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.1>`_
flow (with `PKCE <https://datatracker.ietf.org/doc/html/rfc7636>`_ support).
It allows to exchange an authorization code for an access token.
The client ID and secret must be sent in the POST body.
It is recommended to use PKCE to provide a better security.
Scopes
~~~~~~
The following scopes are available:
- ``application:write``: grants write access to application configuration (only for users with administration rights),
- ``profile:read``: grants read access to auth endpoints,
- ``profile:write``: grants write access to auth endpoints,
- ``users:read``: grants read access to users endpoints,
- ``users:write``: grants write access to users endpoints,
- ``workouts:read``: grants read access to workouts-related endpoints,
- ``workouts:write``: grants write access to workouts-related endpoints.
Flow
~~~~
- The user creates an App (client) on FitTrackee for a third-party application.
.. figure:: _images/fittrackee_screenshot-07.png
:alt: OAuth2 client creation on FitTrackee
| After registration, the client id and secret are shown.
| They must be stored in the 3rd-party application by the user.
- | The 3rd-party app needs to redirect to FitTrackee, in order for the user to authorize the 3rd-party app to access user data on FitTrackee.
.. figure:: _images/fittrackee_screenshot-08.png
:alt: App authorization on FitTrackee
| The authorization URL is ``https://<FITTRACKEE_HOST>/profile/apps/authorize``.
| The required parameters are:
- ``client_id``: the client id displayed after registration
- ``response_type``: ``code``, since FitTrackee only supports Authorization Code flow.
- ``scope``: scopes separated with space.
| and optional parameters:
- ``state``: unique value to prevent cross-site request forgery
| For PKCE, the following parameters are mandatory:
- ``code_challenge``: string generated from a code verifier
- ``code_challenge_method``: method used to create challenge, for instance "S256"
| Example for PKCE:
| ``https://<FITTRACKEE_HOST>/profile/apps/authorize?response_type=code&client_id=<CLIENT_ID>&scope=profile%3Aread+workouts%3Awrite&state=<STATE>&code_challenge=<CODE_CHALLENGE>&code_challenge_method=S256``
- | After the authorization, FitTrackee redirects to the 3rd-party app, so the 3rd-party app can get the authorization code from the redirect URL and then fetches an access token with the client id and secret (endpoint `/api/oauth/token <https://samr1.github.io/FitTrackee/api/oauth2.html#post--api-oauth-token>`_).
| Example of a redirect URL:
| ``https://example.com/callback?code=<AUTHORIZATION_CODE>&state=<STATE>``
.. note::
OAuth2 support is implemented with `Authlib <https://docs.authlib.org/en/latest/>`_ library.
.. warning::
| If FitTrackee is running behind a proxy, the ``X-Forwarded-Proto`` header must be set.
| For instance for ``nginx``:
.. code-block::
proxy_set_header X-Forwarded-Proto $scheme;
Resources
~~~~~~~~~
Some resources about OAuth 2.0:
- `OAuth 2.0 Simplified <https://www.oauth.com>`_ by `Aaron Parecki <https://aaronparecki.com>`_ (example for `authorization code flow with PKCE <https://www.oauth.com/oauth2-servers/server-side-apps/example-flow/>`_)
- `Web App Example of OAuth 2 web application flow <https://requests-oauthlib.readthedocs.io/en/latest/examples/real_world_example.html>`_ with Requests-OAuthlib (python)
- `OAuth 2 Session <https://docs.authlib.org/en/latest/client/oauth2.html#oauth-2-session>`_ with Authlib (python)
- `Minimal example of an application interacting with FitTrackee <https://codeberg.org/SamR1/ft-oauth-client>`_ (python)

7
docs/en/_sources/third_party_tools.rst.txt Normal file
View File

@ -0,0 +1,7 @@
Third-party tools
#################
Thanks to the contributors, the following tools are available:
- `strava-to-fittrackee <https://github.com/jat255/strava-to-fittrackee>`_ (import workouts from a Strava account)
- `FitTrackee Uploader <https://github.com/ebrithiljonas/fittrackee-uploader>`_ (upload .gpx and .fit files)

36
docs/en/_sources/troubleshooting/administrator.rst.txt Normal file
View File

@ -0,0 +1,36 @@
Administrator
#############
`FitTrackee fails to start`
~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Check the database URL in `environment variables <../installation.html#envvar-DATABASE_URL>`__ if the following error is displayed in **gunicorn** logs:
.. code::
sqlalchemy.exc.NoSuchModuleError: Can't load plugin: sqlalchemy.dialects:postgres
It must start with ``postgresql://`` (engine URLs starting with ``postgres://`` are no longer supported).
- Check the email URL in `environment variables <../installation.html#envvar-EMAIL_URL>`__ if the following error is displayed in **gunicorn** logs:
.. code::
fittrackee.emails.exceptions.InvalidEmailUrlScheme
A valid ``EMAIL_URL`` must be provided (see `emails <../installation.html#emails>`__).
`Map images are not displayed but map is shown in Workout detail`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Check the path in `environment variables <../installation.html#envvar-UPLOAD_FOLDER>`__. ``UPLOAD_FOLDER`` must be set with an absolute path.
`Failed to upload or download files`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Check ``client_max_body_size`` in **nginx** config. Increase the value to handle larger files (see **nginx** `documentation <https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size>`_).
- Increase **gunicorn** `timeout <https://docs.gunicorn.org/en/stable/settings.html#timeout>`__ value if the following error is displayed in gunicorn log: ``[CRITICAL] WORKER TIMEOUT``.

7
docs/en/_sources/troubleshooting/index.rst.txt Normal file
View File

@ -0,0 +1,7 @@
Troubleshooting
#################
.. toctree::
:maxdepth: 2
administrator