234 lines
7.7 KiB
ReStructuredText
234 lines
7.7 KiB
ReStructuredText
Installation
|
|
############
|
|
|
|
This application is written in Python (API) and Javascript (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
|
|
- `python-forecast.io <https://github.com/ZeevG/python-forecast.io>`_ to fetch weather data from `Dark Sky <https://darksky.net>`__ (former forecast.io)
|
|
- `dramatiq <https://flask-dramatiq.readthedocs.io/en/latest/>`_ for task queue
|
|
- Client:
|
|
- React/Redux
|
|
- `Leaflet <https://leafletjs.com/>`__ to display map
|
|
- `Recharts <https://github.com/recharts/recharts>`__ to display charts with elevation and speed
|
|
|
|
Sports and weather icons are made by `Freepik <https://www.freepik.com/>`__ from `www.flaticon.com <https://www.flaticon.com/>`__.
|
|
|
|
Prerequisites
|
|
~~~~~~~~~~~~~
|
|
|
|
- PostgreSQL database (10+)
|
|
- Redis for task queue
|
|
- Python 3.7+
|
|
- `Poetry <https://poetry.eustace.io>`__
|
|
- `Yarn <https://yarnpkg.com>`__ and
|
|
`serve <https://github.com/zeit/serve>`__
|
|
- API key from `Dark Sky <https://darksky.net/dev>`__ [not mandatory]
|
|
- SMTP provider
|
|
|
|
|
|
Installation
|
|
~~~~~~~~~~~~
|
|
|
|
| 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.
|
|
|
|
.. 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.5
|
|
|
|
# optional
|
|
$ poetry config virtualenvs.in-project true
|
|
|
|
For other OS, see `Poetry Documentation <https://python-poetry.org/docs/#installation>`__
|
|
|
|
|
|
Dev environment
|
|
^^^^^^^^^^^^^^^
|
|
|
|
- Clone this repo:
|
|
|
|
.. code:: bash
|
|
|
|
$ git clone https://github.com/SamR1/FitTrackee.git
|
|
$ cd FitTrackee
|
|
|
|
- Update **Makefile.config** file if needed and copy/paste the
|
|
**ThunderForest** and **Dark Sky** API keys value in
|
|
**Makefile.custom.config** file (see `Environment variables <installation.html#environment-variables>`__).
|
|
|
|
- Install Python virtualenv, React 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 login (the email is ``admin@example.com``
|
|
and the password ``mpwoadmin``) or register
|
|
|
|
Prod environment
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
.. warning::
|
|
Note that FitTrackee is not production-ready yet
|
|
|
|
- Download the last release (for now, it is the beta release v0.3.0):
|
|
|
|
.. code:: bash
|
|
|
|
$ wget https://github.com/SamR1/FitTrackee/archive/v0.3.0-beta.tar.gz
|
|
$ tar -xzf v0.3.0-beta.tar.gz
|
|
$ mv FitTrackee-0.3.0-beta FitTrackee
|
|
$ cd FitTrackee
|
|
|
|
- Update **Makefile.config** file if needed and copy/paste the
|
|
**ThunderForest** and **Dark Sky** API keys value in
|
|
**Makefile.custom.config** file (see `Environment variables <installation.html#environment-variables>`__).
|
|
|
|
- Install Python virtualenv, React and all related packages and
|
|
initialize the database:
|
|
|
|
.. code:: bash
|
|
|
|
$ make install
|
|
$ make install-db
|
|
|
|
- Build the client:
|
|
|
|
.. code:: bash
|
|
|
|
$ make build-client
|
|
|
|
- Start the server and the client:
|
|
|
|
.. code:: bash
|
|
|
|
$ make run
|
|
|
|
- Run dramatiq workers:
|
|
|
|
.. code:: bash
|
|
|
|
$ make run-workers
|
|
|
|
Open http://localhost:3000, 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 <https://www.postgresql.org/docs/11/app-pgdump.html>`__ for instance)
|
|
| - upload directory: **FitTrackee/fittrackee/fittrackee_api/uploads/**
|
|
|
|
|
|
Dev environment
|
|
^^^^^^^^^^^^^^^
|
|
|
|
- Stop the application and pull the repository:
|
|
|
|
.. code:: bash
|
|
|
|
$ git pull
|
|
|
|
- Update **Makefile.config** and **Makefile.custom.config** file if needed
|
|
|
|
- Upgrade packages and database:
|
|
|
|
.. code:: bash
|
|
|
|
$ make install-dev
|
|
$ make upgrade-db
|
|
|
|
- Restart the server and the client:
|
|
|
|
.. code:: bash
|
|
|
|
$ make serve
|
|
|
|
|
|
Prod environment
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
``TODO``
|
|
|
|
|
|
Environment variables
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The following environment variables must be defined in **Makefile.custom.config**:
|
|
|
|
.. cssclass:: table-bordered table-striped
|
|
|
|
===================================== ============================================== ====================================
|
|
variable description app default value
|
|
===================================== ============================================== ====================================
|
|
``REACT_APP_API_URL`` Fittrackee API URL no default value, must be initialized
|
|
``REACT_APP_GPX_LIMIT_IMPORT`` max. number of gpx file in zip archive 10 (*deprecated in 0.3.0*)
|
|
``REACT_APP_MAX_SINGLE_FILE_SIZE`` max. size of a gpx or picture file 1MB (*deprecated in 0.3.0*)
|
|
``REACT_APP_MAX_ZIP_FILE_SIZE`` max. size of a zip archive 10MB (*deprecated in 0.3.0*)
|
|
``REACT_APP_ALLOW_REGISTRATION`` allows users to register true (*deprecated in 0.3.0*)
|
|
``REACT_APP_THUNDERFOREST_API_KEY`` ThunderForest API key (*deprecated in 0.x.x*, use ``TILE_SERVER_URL`` **and** ``MAP_ATTRIBUTION`` instead)
|
|
``TILE_SERVER_URL`` Tile server URL (with api key if needed) ``https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png``
|
|
``MAP_ATTRIBUTION`` Map attribution (if using another tile server) ``© <a href="http://www.openstreetmap.org/copyright" target="_blank" rel="noopener noreferrer">OpenStreetMap</a> contributors``
|
|
``UI_URL`` application URL no default value, must be initialized
|
|
``EMAIL_URL`` email URL with credentials no default value, must be initialized (see below)
|
|
``SENDER_EMAIL`` application sender email address no default value, must be initialized
|
|
``REDIS_URL`` Redis instance used by Dramatiq local Redis instance
|
|
``WORKERS_PROCESSES`` number of process used by Dramatiq no default value, must be initialized
|
|
===================================== ============================================== ====================================
|
|
|
|
.. warning::
|
|
Since FitTrackee 0.3.0, some applications parameters are now stored in database.
|
|
Related environment variables are needed to initialize database.
|
|
|
|
Emails
|
|
^^^^^^
|
|
*new in 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
|
|
^^^^^^^^^^^^^^^
|
|
*new in 0.x.x*
|
|
|
|
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/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=© <a href="http://www.thunderforest.com/">Thunderforest</a>, © <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors``
|
|
|
|
.. note::
|
|
Check the terms of service of tile provider for map attribution |