Installation ############ This application is written in Python (API) and Typescript (client): - API: - Flask - `gpxpy `_ to parse gpx files - `staticmap `_ to generate a static map image from gpx coordinates - `python-forecast.io `_ to fetch weather data from `Dark Sky `__ (former forecast.io) - `dramatiq `_ for task queue - Client: - Vue3/Vuex - `Leaflet `__ to display map - `Chart.js `__ to display charts with elevation and speed Logo, sports and weather icons are made by `Freepik `__ from `www.flaticon.com `__. Prerequisites ~~~~~~~~~~~~~ - PostgreSQL database (10+) - Redis for task queue - Python 3.7+ - `Poetry `__ (for installation from sources only) - API key from `Dark Sky `__ [not mandatory] - SMTP provider - `Yarn `__ (for development only) - Docker (for development only, to start `MailHog `__ or for evaluation purposes) .. 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: 0.0.0.0 .. 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. .. 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 Directory containing uploaded files. :default: `fittrackee/uploads/` .. danger:: | With installation from PyPI, the directory will be located in **virtualenv** directory if the variable is not initialized. .. 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`` .. danger:: | Since `SQLAlchemy update (1.4+) `__, 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 `__. :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 `__. .. 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**. :default: local Redis instance (``redis://``) .. envvar:: WORKERS_PROCESSES .. versionadded:: 0.3.0 Number of processes used by **Dramatiq**. .. envvar:: TILE_SERVER_URL .. versionadded:: 0.4.0 | Tile server URL (with api key if needed), see `Map tile server `__. | Since **0.4.9**, it's also used to generate static maps (to keep default server, see `DEFAULT_STATICMAP `__) :default: `https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png` .. envvar:: MAP_ATTRIBUTION .. versionadded:: 0.4.0 Map attribution (if using another tile server), see `Map tile server `__. :default: `© OpenStreetMap contributors` .. envvar:: DEFAULT_STATICMAP 🆕 .. versionadded:: 0.4.9 If `True`, it keeps using default tile server to generate static maps. :default: False .. envvar:: WEATHER_API_KEY .. versionchanged:: 0.4.0 ⚠️ replaces ``WEATHER_API`` **Dark Sky** API key for weather data (not mandatory). .. 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`` 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 `__). 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=© Thunderforest, © OpenStreetMap contributors`` .. note:: | Check the terms of service of tile provider for map attribution From PyPI ~~~~~~~~~ .. note:: | Recommended way on production. .. warning:: | Note that FitTrackee is under heavy development, some features may be unstable. Installation ^^^^^^^^^^^^ - Create and activate a virtualenv - Install **FitTrackee** with pip .. code-block:: bash $ pip install fittrackee - Create ``fittrackee`` database Example : .. code-block:: sql CREATE DATABASE fittrackee; CREATE USER fittrackee WITH PASSWORD ''; GRANT ALL PRIVILEGES ON DATABASE fittrackee TO fittrackee; - Initialize environment variables, see `Environment variables `__ For instance, copy and update ``.env`` file from ``.env.example`` and source the file. .. code-block:: bash $ nano .env $ source .env - Upgrade database schema .. code-block:: bash $ fittrackee_upgrade_db - Initialize database .. code-block:: bash $ fittrackee_init_data - Start the application .. code-block:: bash $ fittrackee - Start task queue workers .. code-block:: bash $ fittrackee_worker --processes 2 .. note:: | To start application and workers with **systemd** service, see `Deployment `__ Upgrade ^^^^^^^ .. warning:: | Before upgrading, make a backup of all data: | - database (with `pg_dump `__ for instance) | - upload directory (see `Environment variables `__) - 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 .. code-block:: bash $ fittrackee_upgrade_db - Restart the application and task queue workers. From sources ~~~~~~~~~~~~~ .. warning:: | Since FitTrackee 0.2.1, Python packages installation needs Poetry. | To install it on ArchLinux: .. code-block:: bash $ yay poetry $ poetry --version Poetry 1.0.17 # optional $ poetry config virtualenvs.in-project true For other OS, see `Poetry Documentation `__ Installation ^^^^^^^^^^^^ 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 `__). - 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 log in (the email is ``admin@example.com`` and the password ``mpwoadmin``) or register 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.5.0): .. code:: bash $ wget https://github.com/SamR1/FitTrackee/archive/v0.5.0.tar.gz $ tar -xzf v0.5.0.tar.gz $ mv FitTrackee-0.5.0 FitTrackee $ cd FitTrackee - Create **.env** from example and update it (see `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 Open http://localhost:5000, log in as admin (the email is ``admin@example.com`` and the password ``mpwoadmin``) and change the password Upgrade ^^^^^^^ .. warning:: | Before upgrading, make a backup of all data: | - database (with `pg_dump `__ for instance) | - upload directory (see `Environment variables `__) Dev environment """"""""""""""" - Stop the application and pull the repository: .. code:: bash $ git pull - Update **.env** if needed (see `Environment variables `__). - Upgrade packages and database: .. code:: bash $ make install-dev $ 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.5.0) and overwrite existing files: .. code:: bash $ wget https://github.com/SamR1/FitTrackee/archive/v0.5.0.tar.gz $ tar -xzf v0.5.0.tar.gz $ cp -R FitTrackee-0.5.0/* FitTrackee/ $ cd FitTrackee - Update **.env** if needed (see `Environment variables `__). - Upgrade packages and database: .. code:: bash $ make install-python $ make upgrade-db - Restart the server and dramatiq workers: .. code:: bash $ make run Deployment ~~~~~~~~~~~~~ There are several ways to start **FitTrackee** web application and task queue library. One way is to use a **systemd** services and **Nginx** to proxy pass to **Gunicorn**. Examples (to update depending on your application configuration and given distribution): - for application: ``fittrackee.service`` .. 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= StandardOutput=syslog StandardError=syslog SyslogIdentifier=fittrackee Environment="APP_SECRET_KEY=" Environment="APP_LOG=" Environment="UPLOAD_FOLDER=" Environment="DATABASE_URL=" Environment="UI_URL=" Environment="EMAIL_URL=" Environment="SENDER_EMAIL=" Environment="REDIS_URL=" Environment="TILE_SERVER_URL=" Environment="MAP_ATTRIBUTION=" Environment="WEATHER_API_KEY=" WorkingDirectory=/home// ExecStart=/home///.venv/bin/gunicorn -b 127.0.0.1:5000 "fittrackee:create_app()" --error-logfile /home///gunicorn.log Restart=always [Install] WantedBy=multi-user.target .. note:: More information on `Gunicorn documentation `__ - 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= 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// ExecStart=/home///.venv/bin/flask worker --processes Restart=always [Install] WantedBy=multi-user.target - **Nginx** configuration: .. code-block:: server { listen 443 ssl; server_name example.com; ssl_certificate fullchain.pem; ssl_certificate_key privkey.pem; location / { proxy_pass http://127.0.0.1:5000; proxy_redirect default; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Host $server_name; } } server { listen 80; server_name example.com; location / { return 301 https://example.com$request_uri; } } .. note:: If needed, update configuration to handle larger files (see `client_max_body_size `_). Docker ~~~~~~ Installation ^^^^^^^^^^^^ .. versionadded:: 0.4.4 For evaluation purposes , docker files are available, installing **FitTrackee** from **sources**. - To install **FitTrackee** with database initialisation and run the application and dramatiq workers: .. code-block:: bash $ git clone https://github.com/SamR1/FitTrackee.git $ cd FitTrackee $ make docker-build docker-run docker-init Open http://localhost:5000, log in as admin (the email is `admin@example.com` and the password `mpwoadmin`) or register. Open http://localhost:8025 to access `MailHog interface `_ (email testing tool) - To stop **Fittrackee**: .. 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 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 and log in (the email is ``admin@example.com`` and the password ``mpwoadmin``) or register .. note:: Some environment variables need to be updated like `UI_URL`