FitTrackee/docs/installation.html
2023-04-12 17:32:13 +02:00

1234 lines
68 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<title>Installation &#8212; FitTrackee 0.7.15
documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/bootstrap-sphinx.css" />
<link rel="stylesheet" type="text/css" href="_static/css/fork-awesome.min.css" />
<link rel="stylesheet" type="text/css" href="_static/css/custom.css" />
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/sphinx_highlight.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Command line interface" href="cli.html" />
<link rel="prev" title="OAuth 2.0" href="oauth.html" />
<meta charset='utf-8'>
<meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
<meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
<meta name="apple-mobile-web-app-capable" content="yes">
<script type="text/javascript" src="_static/js/jquery-1.12.4.min.js"></script>
<script type="text/javascript" src="_static/js/jquery-fix.js"></script>
<script type="text/javascript" src="_static/bootstrap-3.4.1/js/bootstrap.min.js"></script>
<script type="text/javascript" src="_static/bootstrap-sphinx.js"></script>
</head><body>
<div id="navbar" class="navbar navbar-default navbar-fixed-top">
<div class="container">
<div class="navbar-header">
<!-- .btn-navbar is used as the toggle for collapsed navbar content -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="index.html">
FitTrackee</a>
<span class="navbar-text navbar-version pull-left"><b>0.7.15
</b></span>
</div>
<div class="collapse navbar-collapse nav-collapse">
<ul class="nav navbar-nav">
<li><a href="https://github.com/SamR1/FitTrackee">GitHub</a></li>
<li class="dropdown globaltoc-container">
<a role="button"
id="dLabelGlobalToc"
data-toggle="dropdown"
data-target="#"
href="index.html">Docs <b class="caret"></b></a>
<ul class="dropdown-menu globaltoc"
role="menu"
aria-labelledby="dLabelGlobalToc"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="features.html">Features</a></li>
<li class="toctree-l1"><a class="reference internal" href="oauth.html">OAuth 2.0</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="cli.html">Command line interface</a></li>
<li class="toctree-l1"><a class="reference internal" href="third_party_tools.html">Third-party tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="api/index.html">API documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="troubleshooting/index.html">Troubleshooting</a></li>
<li class="toctree-l1"><a class="reference internal" href="changelog.html">Change log</a></li>
</ul>
</ul>
</li>
<li class="dropdown">
<a role="button"
id="dLabelLocalToc"
data-toggle="dropdown"
data-target="#"
href="#">Page <b class="caret"></b></a>
<ul class="dropdown-menu localtoc"
role="menu"
aria-labelledby="dLabelLocalToc"><ul>
<li><a class="reference internal" href="#">Installation</a><ul>
<li><a class="reference internal" href="#prerequisites">Prerequisites</a></li>
<li><a class="reference internal" href="#environment-variables">Environment variables</a><ul>
<li><a class="reference internal" href="#emails">Emails</a></li>
<li><a class="reference internal" href="#map-tile-server">Map tile server</a></li>
<li><a class="reference internal" href="#api-rate-limits">API rate limits</a></li>
<li><a class="reference internal" href="#weather-data">Weather data</a></li>
</ul>
</li>
<li><a class="reference internal" href="#id2">Installation</a><ul>
<li><a class="reference internal" href="#from-pypi">From PyPI</a></li>
<li><a class="reference internal" href="#from-sources">From sources</a><ul>
<li><a class="reference internal" href="#dev-environment">Dev environment</a></li>
<li><a class="reference internal" href="#production-environment">Production environment</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#upgrade">Upgrade</a><ul>
<li><a class="reference internal" href="#id3">From PyPI</a></li>
<li><a class="reference internal" href="#id4">From sources</a><ul>
<li><a class="reference internal" href="#id5">Dev environment</a></li>
<li><a class="reference internal" href="#prod-environment">Prod environment</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#deployment">Deployment</a></li>
<li><a class="reference internal" href="#docker">Docker</a><ul>
<li><a class="reference internal" href="#id6">Installation</a></li>
<li><a class="reference internal" href="#development">Development</a></li>
</ul>
</li>
<li><a class="reference internal" href="#yunohost">Yunohost</a></li>
</ul>
</li>
</ul>
</ul>
</li>
<li>
<a href="oauth.html" title="Previous Chapter: OAuth 2.0"><span class="glyphicon glyphicon-chevron-left visible-sm"></span><span class="hidden-sm hidden-tablet">&laquo; OAuth 2.0</span>
</a>
</li>
<li>
<a href="cli.html" title="Next Chapter: Command line interface"><span class="glyphicon glyphicon-chevron-right visible-sm"></span><span class="hidden-sm hidden-tablet">Command line ... &raquo;</span>
</a>
</li>
<li class="hidden-sm">
<div id="sourcelink">
<a href="_sources/installation.rst.txt"
rel="nofollow">Source</a>
</div></li>
</ul>
<form class="navbar-form navbar-right" action="search.html" method="get">
<div class="form-group">
<input type="text" name="q" class="form-control" placeholder="Search" />
</div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
</div>
<div class="container">
<div class="row">
<div class="body col-md-12 content" role="main">
<section id="installation">
<h1>Installation<a class="headerlink" href="#installation" title="Permalink to this heading"></a></h1>
<p>This application is written in Python (API) and Typescript (client):</p>
<ul class="simple">
<li><dl class="simple">
<dt>API:</dt><dd><ul>
<li><p>Flask</p></li>
<li><p><a class="reference external" href="https://github.com/tkrajina/gpxpy">gpxpy</a> to parse gpx files</p></li>
<li><p><a class="reference external" href="https://github.com/komoot/staticmap">staticmap</a> to generate a static map image from gpx coordinates</p></li>
<li><p><a class="reference external" href="https://flask-dramatiq.readthedocs.io/en/latest/">dramatiq</a> for task queue</p></li>
<li><p><a class="reference external" href="https://docs.authlib.org/en/latest/">Authlib</a> for OAuth 2.0 Authorization support</p></li>
<li><p><a class="reference external" href="https://flask-limiter.readthedocs.io/en/stable">Flask-Limiter</a> for API rate limits</p></li>
</ul>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>Client:</dt><dd><ul>
<li><p>Vue3/Vuex</p></li>
<li><p><a class="reference external" href="https://leafletjs.com/">Leaflet</a> to display map</p></li>
<li><p><a class="reference external" href="https://www.chartjs.org/">Chart.js</a> to display charts with elevation and speed</p></li>
</ul>
</dd>
</dl>
</li>
</ul>
<div class="line-block">
<div class="line">Logo, some sports and weather icons are made by <a class="reference external" href="https://www.freepik.com/">Freepik</a> from <a class="reference external" href="https://www.flaticon.com/">www.flaticon.com</a>.</div>
<div class="line">FitTrackee also uses icons from <a class="reference external" href="https://forkaweso.me">Fork Awesome</a>.</div>
</div>
<section id="prerequisites">
<h2>Prerequisites<a class="headerlink" href="#prerequisites" title="Permalink to this heading"></a></h2>
<ul class="simple">
<li><dl class="simple">
<dt>mandatory</dt><dd><ul>
<li><p>Python 3.7+</p></li>
<li><p>PostgreSQL 11+</p></li>
</ul>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>optional</dt><dd><ul>
<li><p>Redis for task queue (if email sending is enabled and for data export requests) and API rate limits</p></li>
<li><p>SMTP provider (if email sending is enabled)</p></li>
<li><p>API key from a <a class="reference external" href="installation.html#weather-data">weather data provider</a></p></li>
<li><p><a class="reference external" href="https://poetry.eustace.io">Poetry</a> (for installation from sources only)</p></li>
<li><p><a class="reference external" href="https://yarnpkg.com">Yarn</a> (for development only)</p></li>
<li><p>Docker and Docker Compose (for development or evaluation purposes)</p></li>
</ul>
</dd>
</dl>
</li>
</ul>
<div class="admonition note">
<p class="admonition-title">Note</p>
<div class="line-block">
<div class="line">If registration is enabled, it is recommended to set Redis and a SMTP provider for email sending and data export requests.</div>
</div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<div class="line-block">
<div class="line">The following steps describe an installation on Linux systems (tested
on Debian and Arch).</div>
<div class="line">On other OS, some issues can be encountered and adaptations may be
necessary.</div>
</div>
</div>
</section>
<section id="environment-variables">
<h2>Environment variables<a class="headerlink" href="#environment-variables" title="Permalink to this heading"></a></h2>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<div class="line-block">
<div class="line">Since FitTrackee 0.4.0, <code class="docutils literal notranslate"><span class="pre">Makefile.custom.config</span></code> is replaced by <code class="docutils literal notranslate"><span class="pre">.env</span></code></div>
</div>
</div>
<p>The following environment variables are used by <strong>FitTrackee</strong> web application
or the task processing library. They are not all mandatory depending on
deployment method.</p>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-FLASK_APP">
<span class="sig-name descname"><span class="pre">FLASK_APP</span></span><a class="headerlink" href="#envvar-FLASK_APP" title="Permalink to this definition"></a></dt>
<dd><div class="line-block">
<div class="line">Name of the module to import at flask run.</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">FLASK_APP</span></code> should contain <code class="docutils literal notranslate"><span class="pre">$(PWD)/fittrackee/__main__.py</span></code> with installation from sources, else <code class="docutils literal notranslate"><span class="pre">fittrackee</span></code>.</div>
</div>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-HOST">
<span class="sig-name descname"><span class="pre">HOST</span></span><a class="headerlink" href="#envvar-HOST" title="Permalink to this definition"></a></dt>
<dd><p><strong>FitTrackee</strong> host.</p>
<dl class="field-list simple">
<dt class="field-odd">Default<span class="colon">:</span></dt>
<dd class="field-odd"><p>127.0.0.1</p>
</dd>
</dl>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-PORT">
<span class="sig-name descname"><span class="pre">PORT</span></span><a class="headerlink" href="#envvar-PORT" title="Permalink to this definition"></a></dt>
<dd><p><strong>FitTrackee</strong> port.</p>
<dl class="field-list simple">
<dt class="field-odd">Default<span class="colon">:</span></dt>
<dd class="field-odd"><p>5000</p>
</dd>
</dl>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-APP_SETTINGS">
<span class="sig-name descname"><span class="pre">APP_SETTINGS</span></span><a class="headerlink" href="#envvar-APP_SETTINGS" title="Permalink to this definition"></a></dt>
<dd><p><strong>FitTrackee</strong> configuration.</p>
<dl class="field-list simple">
<dt class="field-odd">Default<span class="colon">:</span></dt>
<dd class="field-odd"><p>fittrackee.config.ProductionConfig</p>
</dd>
</dl>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-APP_SECRET_KEY">
<span class="sig-name descname"><span class="pre">APP_SECRET_KEY</span></span><a class="headerlink" href="#envvar-APP_SECRET_KEY" title="Permalink to this definition"></a></dt>
<dd><p><strong>FitTrackee</strong> secret key, must be initialized in production environment.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Use a strong secret key. This key is used in JWT generation.</p>
</div>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-APP_WORKERS">
<span class="sig-name descname"><span class="pre">APP_WORKERS</span></span><a class="headerlink" href="#envvar-APP_WORKERS" title="Permalink to this definition"></a></dt>
<dd><p>Number of workers spawned by <strong>Gunicorn</strong>.</p>
<dl class="field-list simple">
<dt class="field-odd">Default<span class="colon">:</span></dt>
<dd class="field-odd"><p>1</p>
</dd>
</dl>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-APP_LOG">
<span class="sig-name descname"><span class="pre">APP_LOG</span></span><a class="headerlink" href="#envvar-APP_LOG" title="Permalink to this definition"></a></dt>
<dd><div class="versionadded">
<p><span class="versionmodified added">New in version 0.4.0.</span></p>
</div>
<p>Path to log file</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-UPLOAD_FOLDER">
<span class="sig-name descname"><span class="pre">UPLOAD_FOLDER</span></span><a class="headerlink" href="#envvar-UPLOAD_FOLDER" title="Permalink to this definition"></a></dt>
<dd><div class="versionadded">
<p><span class="versionmodified added">New in version 0.4.0.</span></p>
</div>
<p><strong>Absolute path</strong> to the directory where <cite>uploads</cite> folder will be created.</p>
<dl class="field-list simple">
<dt class="field-odd">Default<span class="colon">:</span></dt>
<dd class="field-odd"><p><cite>&lt;application_directory&gt;/fittrackee</cite></p>
</dd>
</dl>
<div class="admonition danger">
<p class="admonition-title">Danger</p>
<div class="line-block">
<div class="line">With installation from PyPI, the directory will be located in
<strong>virtualenv</strong> directory if the variable is not initialized.</div>
</div>
</div>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-DATABASE_URL">
<span class="sig-name descname"><span class="pre">DATABASE_URL</span></span><a class="headerlink" href="#envvar-DATABASE_URL" title="Permalink to this definition"></a></dt>
<dd><div class="line-block">
<div class="line">Database URL with username and password, must be initialized in production environment.</div>
<div class="line">For example in dev environment : <code class="docutils literal notranslate"><span class="pre">postgresql://fittrackee:fittrackee&#64;localhost:5432/fittrackee</span></code></div>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<div class="line-block">
<div class="line">Since <a class="reference external" href="https://docs.sqlalchemy.org/en/14/changelog/changelog_14.html#change-3687655465c25a39b968b4f5f6e9170b">SQLAlchemy update (1.4+)</a>,
engine URL should begin with <cite>postgresql://</cite>.</div>
</div>
</div>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-DATABASE_DISABLE_POOLING">
<span class="sig-name descname"><span class="pre">DATABASE_DISABLE_POOLING</span></span><a class="headerlink" href="#envvar-DATABASE_DISABLE_POOLING" title="Permalink to this definition"></a></dt>
<dd><div class="versionadded">
<p><span class="versionmodified added">New in version 0.4.0.</span></p>
</div>
<p>Disable pooling if needed (when starting application with <strong>FitTrackee</strong> entry point and not directly with <strong>Gunicorn</strong>),
see <a class="reference external" href="https://docs.sqlalchemy.org/en/13/core/pooling.html#using-connection-pools-with-multiprocessing-or-os-fork">SqlAlchemy documentation</a>.</p>
<dl class="field-list simple">
<dt class="field-odd">Default<span class="colon">:</span></dt>
<dd class="field-odd"><p>false</p>
</dd>
</dl>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-UI_URL">
<span class="sig-name descname"><span class="pre">UI_URL</span></span><a class="headerlink" href="#envvar-UI_URL" title="Permalink to this definition"></a></dt>
<dd><p><strong>FitTrackee</strong> URL, needed for links in emails.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-EMAIL_URL">
<span class="sig-name descname"><span class="pre">EMAIL_URL</span></span><a class="headerlink" href="#envvar-EMAIL_URL" title="Permalink to this definition"></a></dt>
<dd><div class="versionadded">
<p><span class="versionmodified added">New in version 0.3.0.</span></p>
</div>
<p>Email URL with credentials, see <a class="reference external" href="installation.html#emails">Emails</a>.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 0.6.5.</span></p>
</div>
<dl class="field-list simple">
<dt class="field-odd">Default<span class="colon">:</span></dt>
<dd class="field-odd"><p>empty string</p>
</dd>
</dl>
<div class="admonition danger">
<p class="admonition-title">Danger</p>
<p>If the email URL is empty, email sending will be disabled.</p>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>If the email URL is invalid, the application may not start.</p>
</div>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-SENDER_EMAIL">
<span class="sig-name descname"><span class="pre">SENDER_EMAIL</span></span><a class="headerlink" href="#envvar-SENDER_EMAIL" title="Permalink to this definition"></a></dt>
<dd><div class="versionadded">
<p><span class="versionmodified added">New in version 0.3.0.</span></p>
</div>
<p><strong>FitTrackee</strong> sender email address.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-REDIS_URL">
<span class="sig-name descname"><span class="pre">REDIS_URL</span></span><a class="headerlink" href="#envvar-REDIS_URL" title="Permalink to this definition"></a></dt>
<dd><div class="versionadded">
<p><span class="versionmodified added">New in version 0.3.0.</span></p>
</div>
<p>Redis instance used by <strong>Dramatiq</strong> and <strong>Flask-Limiter</strong>.</p>
<dl class="field-list simple">
<dt class="field-odd">Default<span class="colon">:</span></dt>
<dd class="field-odd"><p>local Redis instance (<code class="docutils literal notranslate"><span class="pre">redis://</span></code>)</p>
</dd>
</dl>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-WORKERS_PROCESSES">
<span class="sig-name descname"><span class="pre">WORKERS_PROCESSES</span></span><a class="headerlink" href="#envvar-WORKERS_PROCESSES" title="Permalink to this definition"></a></dt>
<dd><div class="versionadded">
<p><span class="versionmodified added">New in version 0.3.0.</span></p>
</div>
<p>Number of processes used by <strong>Dramatiq</strong>.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-API_RATE_LIMITS">
<span class="sig-name descname"><span class="pre">API_RATE_LIMITS</span></span><a class="headerlink" href="#envvar-API_RATE_LIMITS" title="Permalink to this definition"></a></dt>
<dd><div class="versionadded">
<p><span class="versionmodified added">New in version 0.7.0.</span></p>
</div>
<p>API rate limits, see <a class="reference external" href="installation.html#api-rate-limits">API rate limits</a>.</p>
<dl class="field-list simple">
<dt class="field-odd">Default<span class="colon">:</span></dt>
<dd class="field-odd"><p><cite>300 per 5 minutes</cite></p>
</dd>
</dl>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-TILE_SERVER_URL">
<span class="sig-name descname"><span class="pre">TILE_SERVER_URL</span></span><a class="headerlink" href="#envvar-TILE_SERVER_URL" title="Permalink to this definition"></a></dt>
<dd><div class="versionadded">
<p><span class="versionmodified added">New in version 0.4.0.</span></p>
</div>
<div class="line-block">
<div class="line">Tile server URL (with api key if needed), see <a class="reference external" href="installation.html#map-tile-server">Map tile server</a>.</div>
<div class="line">Since <strong>0.4.9</strong>, its also used to generate static maps (to keep default server, see <a class="reference external" href="installation.html#envvar-DEFAULT_STATICMAP">DEFAULT_STATICMAP</a>)</div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Default<span class="colon">:</span></dt>
<dd class="field-odd"><p><cite>https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png</cite></p>
</dd>
</dl>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-STATICMAP_SUBDOMAINS">
<span class="sig-name descname"><span class="pre">STATICMAP_SUBDOMAINS</span></span><a class="headerlink" href="#envvar-STATICMAP_SUBDOMAINS" title="Permalink to this definition"></a></dt>
<dd><div class="versionadded">
<p><span class="versionmodified added">New in version 0.6.10.</span></p>
</div>
<div class="line-block">
<div class="line">Some tile servers require a subdomain, see <a class="reference external" href="installation.html#map-tile-server">Map tile server</a>.</div>
<div class="line">For instance: “a,b,c” for OSM France.</div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Default<span class="colon">:</span></dt>
<dd class="field-odd"><p>empty string</p>
</dd>
</dl>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-MAP_ATTRIBUTION">
<span class="sig-name descname"><span class="pre">MAP_ATTRIBUTION</span></span><a class="headerlink" href="#envvar-MAP_ATTRIBUTION" title="Permalink to this definition"></a></dt>
<dd><div class="versionadded">
<p><span class="versionmodified added">New in version 0.4.0.</span></p>
</div>
<p>Map attribution (if using another tile server), see <a class="reference external" href="installation.html#map-tile-server">Map tile server</a>.</p>
<dl class="field-list simple">
<dt class="field-odd">Default<span class="colon">:</span></dt>
<dd class="field-odd"><p><cite>&amp;copy; &lt;a href=”http://www.openstreetmap.org/copyright” target=”_blank” rel=”noopener noreferrer”&gt;OpenStreetMap&lt;/a&gt; contributors</cite></p>
</dd>
</dl>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-DEFAULT_STATICMAP">
<span class="sig-name descname"><span class="pre">DEFAULT_STATICMAP</span></span><a class="headerlink" href="#envvar-DEFAULT_STATICMAP" title="Permalink to this definition"></a></dt>
<dd><div class="versionadded">
<p><span class="versionmodified added">New in version 0.4.9.</span></p>
</div>
<div class="line-block">
<div class="line">If <cite>True</cite>, it keeps using default tile server to generate static maps (Komoot.de tile server).</div>
<div class="line">Otherwise, it uses the tile server set in <a class="reference external" href="installation.html#envvar-TILE_SERVER_URL">TILE_SERVER_URL</a>.</div>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 0.6.10.</span></p>
</div>
<div class="line-block">
<div class="line">This variable is now case-insensitive.</div>
<div class="line">If <cite>False</cite>, depending on tile server, <a class="reference external" href="installation.html#envvar-STATICMAP_SUBDOMAINS">subdomains</a> may be mandatory.</div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Default<span class="colon">:</span></dt>
<dd class="field-odd"><p>False</p>
</dd>
</dl>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-WEATHER_API_KEY">
<span class="sig-name descname"><span class="pre">WEATHER_API_KEY</span></span><a class="headerlink" href="#envvar-WEATHER_API_KEY" title="Permalink to this definition"></a></dt>
<dd><div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 0.4.0: </span>⚠️ replaces <code class="docutils literal notranslate"><span class="pre">WEATHER_API</span></code></p>
</div>
<p>Weather API key (not mandatory), see <code class="docutils literal notranslate"><span class="pre">WEATHER_API_PROVIDER</span></code>.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-WEATHER_API_PROVIDER">
<span class="sig-name descname"><span class="pre">WEATHER_API_PROVIDER</span> <span class="pre">🆕</span></span><a class="headerlink" href="#envvar-WEATHER_API_PROVIDER" title="Permalink to this definition"></a></dt>
<dd><div class="versionadded">
<p><span class="versionmodified added">New in version 0.7.11.</span></p>
</div>
<p>Provider for weather data (not mandatory), see <a class="reference external" href="installation.html#weather-data">Weather data</a>.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-VUE_APP_API_URL">
<span class="sig-name descname"><span class="pre">VUE_APP_API_URL</span></span><a class="headerlink" href="#envvar-VUE_APP_API_URL" title="Permalink to this definition"></a></dt>
<dd><p><strong>FitTrackee</strong> API URL, only needed in dev environment.</p>
</dd></dl>
<section id="emails">
<h3>Emails<a class="headerlink" href="#emails" title="Permalink to this heading"></a></h3>
<div class="versionadded">
<p><span class="versionmodified added">New in version 0.3.0.</span></p>
</div>
<p>To send emails, a valid <code class="docutils literal notranslate"><span class="pre">EMAIL_URL</span></code> must be provided:</p>
<ul class="simple">
<li><p>with an unencrypted SMTP server: <code class="docutils literal notranslate"><span class="pre">smtp://username:password&#64;smtp.example.com:25</span></code></p></li>
<li><p>with SSL: <code class="docutils literal notranslate"><span class="pre">smtp://username:password&#64;smtp.example.com:465/?ssl=True</span></code></p></li>
<li><p>with STARTTLS: <code class="docutils literal notranslate"><span class="pre">smtp://username:password&#64;smtp.example.com:587/?tls=True</span></code></p></li>
</ul>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<div class="line-block">
<div class="line">- If the email URL is invalid, the application may not start.</div>
<div class="line">- Sending emails with Office365 may not work if SMTP auth is disabled.</div>
</div>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 0.5.3.</span></p>
</div>
<div class="line-block">
<div class="line">Credentials can be omitted: <code class="docutils literal notranslate"><span class="pre">smtp://smtp.example.com:25</span></code>.</div>
<div class="line">If <code class="docutils literal notranslate"><span class="pre">:&lt;port&gt;</span></code> is omitted, the port defaults to 25.</div>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<div class="line-block">
<div class="line">Since 0.6.0, newly created accounts must be confirmed (an email with confirmation instructions is sent after registration).</div>
</div>
</div>
<p>Emails sent by FitTrackee are:</p>
<ul class="simple">
<li><p>account confirmation instructions</p></li>
<li><p>password reset request</p></li>
<li><p>email change (to old and new email adresses)</p></li>
<li><p>password change</p></li>
<li><p>notification when a data export archive is ready to download (<em>new in 0.7.13</em>)</p></li>
</ul>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 0.6.5.</span></p>
</div>
<p>For single-user instance, it is possible to disable email sending with an empty <code class="docutils literal notranslate"><span class="pre">EMAIL_URL</span></code> (in this case, no need to start dramatiq workers).</p>
<p>A <a class="reference external" href="cli.html#ftcli-users-update">CLI</a> is available to activate account, modify email and password and handle data export requests.</p>
</section>
<section id="map-tile-server">
<h3>Map tile server<a class="headerlink" href="#map-tile-server" title="Permalink to this heading"></a></h3>
<div class="versionadded">
<p><span class="versionmodified added">New in version 0.4.0.</span></p>
</div>
<p>Default tile server is now <strong>OpenStreetMap</strong>s standard tile layer (if environment variables are not initialized).
The tile server can be changed by updating <code class="docutils literal notranslate"><span class="pre">TILE_SERVER_URL</span></code> and <code class="docutils literal notranslate"><span class="pre">MAP_ATTRIBUTION</span></code> variables (<a class="reference external" href="https://wiki.openstreetmap.org/wiki/Raster_tile_providers">list of tile servers</a>).</p>
<p>To keep using <strong>ThunderForest Outdoors</strong>, the configuration is:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">TILE_SERVER_URL=https://{s}.tile.thunderforest.com/outdoors/{z}/{x}/{y}.png?apikey=XXXX</span></code> where <strong>XXXX</strong> is <strong>ThunderForest</strong> API key</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">MAP_ATTRIBUTION=&amp;copy;</span> <span class="pre">&lt;a</span> <span class="pre">href=&quot;http://www.thunderforest.com/&quot;&gt;Thunderforest&lt;/a&gt;,</span> <span class="pre">&amp;copy;</span> <span class="pre">&lt;a</span> <span class="pre">href=&quot;http://www.openstreetmap.org/copyright&quot;&gt;OpenStreetMap&lt;/a&gt;</span> <span class="pre">contributors</span></code></p></li>
</ul>
<div class="admonition note">
<p class="admonition-title">Note</p>
<div class="line-block">
<div class="line">Check the terms of service of tile provider for map attribution.</div>
</div>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 0.6.10.</span></p>
</div>
<p>Since the tile server can be used for static map generation, some servers require a subdomain.</p>
<p>For instance, to set OSM France tile server, the expected values are:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">TILE_SERVER_URL=https://{s}.tile.openstreetmap.fr/osmfr/{z}/{x}/{y}.png</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">MAP_ATTRIBUTION='fond</span> <span class="pre">de</span> <span class="pre">carte</span> <span class="pre">par</span> <span class="pre">&lt;a</span> <span class="pre">href=&quot;http://www.openstreetmap.fr/mentions-legales/&quot;</span> <span class="pre">target=&quot;_blank&quot;</span> <span class="pre">rel=&quot;nofollow</span> <span class="pre">noopener&quot;&gt;OpenStreetMap</span> <span class="pre">France&lt;/a&gt;,</span> <span class="pre">sous&amp;nbsp;&lt;a</span> <span class="pre">href=&quot;http://creativecommons.org/licenses/by-sa/2.0/fr/&quot;</span> <span class="pre">target=&quot;_blank&quot;</span> <span class="pre">rel=&quot;nofollow</span> <span class="pre">noopener&quot;&gt;licence</span> <span class="pre">CC</span> <span class="pre">BY-SA&lt;/a&gt;'</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">STATICMAP_SUBDOMAINS=a,b,c</span></code></p></li>
</ul>
<p>The subdomain will be chosen randomly.</p>
</section>
<section id="api-rate-limits">
<h3>API rate limits<a class="headerlink" href="#api-rate-limits" title="Permalink to this heading"></a></h3>
<div class="versionadded">
<p><span class="versionmodified added">New in version 0.7.0.</span></p>
</div>
<div class="line-block">
<div class="line">API rate limits are managed by <a class="reference external" href="https://flask-limiter.readthedocs.io/en/stable">Flask-Limiter</a>, based on IP with fixed window strategy.</div>
<div class="line">To enable rate limits, <strong>Redis</strong> must be available.</div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<div class="line-block">
<div class="line">If no Redis instance is available for rate limits, FitTrackee can still start.</div>
</div>
</div>
<div class="line-block">
<div class="line">All endpoints are subject to rate limits, except endpoints serving assets.</div>
<div class="line">Limits can be modified by setting the environment variable <code class="docutils literal notranslate"><span class="pre">API_RATE_LIMITS</span></code> (see <a class="reference external" href="https://flask-limiter.readthedocs.io/en/stable/configuration.html#rate-limit-string-notation">Flask-Limiter documentation for notation</a>).</div>
<div class="line">Rate limits must be separated by a comma, for instance:</div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">export</span> <span class="n">API_RATE_LIMITS</span><span class="o">=</span><span class="s2">&quot;200 per day, 50 per hour&quot;</span>
</pre></div>
</div>
<p><strong>Flask-Limiter</strong> provides a <a class="reference external" href="https://flask-limiter.readthedocs.io/en/stable/cli.html">Command Line Interface</a> for maintenance and diagnostic purposes.</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>flask<span class="w"> </span>limiter
Usage:<span class="w"> </span>flask<span class="w"> </span>limiter<span class="w"> </span><span class="o">[</span>OPTIONS<span class="o">]</span><span class="w"> </span>COMMAND<span class="w"> </span><span class="o">[</span>ARGS<span class="o">]</span>...
<span class="w"> </span>Flask-Limiter<span class="w"> </span>maintenance<span class="w"> </span><span class="p">&amp;</span><span class="w"> </span>utility<span class="w"> </span>commmands
Options:
<span class="w"> </span>--help<span class="w"> </span>Show<span class="w"> </span>this<span class="w"> </span>message<span class="w"> </span>and<span class="w"> </span>exit.
Commands:
<span class="w"> </span>clear<span class="w"> </span>Clear<span class="w"> </span>limits<span class="w"> </span><span class="k">for</span><span class="w"> </span>a<span class="w"> </span>specific<span class="w"> </span>key
<span class="w"> </span>config<span class="w"> </span>View<span class="w"> </span>the<span class="w"> </span>extension<span class="w"> </span>configuration
<span class="w"> </span>limits<span class="w"> </span>Enumerate<span class="w"> </span>details<span class="w"> </span>about<span class="w"> </span>all<span class="w"> </span>routes<span class="w"> </span>with<span class="w"> </span>rate<span class="w"> </span>limits
</pre></div>
</div>
</section>
<section id="weather-data">
<h3>Weather data<a class="headerlink" href="#weather-data" title="Permalink to this heading"></a></h3>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 0.7.11.</span></p>
</div>
<p>The following weather data providers are supported by <strong>FitTrackee</strong>:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://www.visualcrossing.com">Visual Crossing</a> (<strong>note</strong>: historical data are provided on hourly period)</p></li>
</ul>
<p>To configure a weather provider, set the following environment variables:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">WEATHER_API_KEY</span></code>: the key to the corresponding weather provider</p></li>
</ul>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 0.7.15.</span></p>
</div>
<p><strong>DarkSky</strong> support is discontinued, since the service shut down on March 31, 2023.</p>
</section>
</section>
<section id="id2">
<h2>Installation<a class="headerlink" href="#id2" title="Permalink to this heading"></a></h2>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<div class="line-block">
<div class="line">Note that FitTrackee is under heavy development, some features may be unstable.</div>
</div>
</div>
<section id="from-pypi">
<h3>From PyPI<a class="headerlink" href="#from-pypi" title="Permalink to this heading"></a></h3>
<div class="admonition note">
<p class="admonition-title">Note</p>
<div class="line-block">
<div class="line">Recommended way on production.</div>
</div>
</div>
<ul class="simple">
<li><p>Create and activate a virtualenv</p></li>
<li><p>Install <strong>FitTrackee</strong> with pip</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>fittrackee
</pre></div>
</div>
<ul class="simple">
<li><p>Create <code class="docutils literal notranslate"><span class="pre">fittrackee</span></code> database</p></li>
</ul>
<p>Example :</p>
<div class="highlight-sql notranslate"><div class="highlight"><pre><span></span><span class="k">CREATE</span><span class="w"> </span><span class="k">USER</span><span class="w"> </span><span class="n">fittrackee</span><span class="w"> </span><span class="k">WITH</span><span class="w"> </span><span class="n">PASSWORD</span><span class="w"> </span><span class="s1">&#39;&lt;PASSWORD&gt;&#39;</span><span class="p">;</span>
<span class="k">CREATE</span><span class="w"> </span><span class="k">SCHEMA</span><span class="w"> </span><span class="n">fittrackee</span><span class="w"> </span><span class="k">AUTHORIZATION</span><span class="w"> </span><span class="n">fittrackee</span><span class="p">;</span>
<span class="k">CREATE</span><span class="w"> </span><span class="k">DATABASE</span><span class="w"> </span><span class="n">fittrackee</span><span class="w"> </span><span class="k">OWNER</span><span class="w"> </span><span class="n">fittrackee</span><span class="p">;</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<div class="line-block">
<div class="line">see PostgreSQL <a class="reference external" href="https://www.postgresql.org/docs/15/ddl-schemas.html">documentation</a> for schema and privileges.</div>
</div>
</div>
<ul class="simple">
<li><p>Initialize environment variables, see <a class="reference external" href="installation.html#environment-variables">Environment variables</a></p></li>
</ul>
<p>For instance, copy and update <code class="docutils literal notranslate"><span class="pre">.env</span></code> file from <code class="docutils literal notranslate"><span class="pre">.env.example</span></code> and source the file.</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>nano<span class="w"> </span>.env
$<span class="w"> </span><span class="nb">source</span><span class="w"> </span>.env
</pre></div>
</div>
<ul class="simple">
<li><p>Initialize database schema</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>ftcli<span class="w"> </span>db<span class="w"> </span>upgrade
</pre></div>
</div>
<ul class="simple">
<li><p>Start the application</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>fittrackee
</pre></div>
</div>
<ul class="simple">
<li><p>Start task queue workers if email sending is enabled, with flask-dramatiq CLI:</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>flask<span class="w"> </span>worker<span class="w"> </span>--processes<span class="w"> </span><span class="m">2</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<div class="line-block">
<div class="line">To start application and workers with <strong>systemd</strong> service, see <a class="reference external" href="installation.html#deployment">Deployment</a></div>
</div>
</div>
<ul class="simple">
<li><p>Open <a class="reference external" href="http://localhost:5000">http://localhost:5000</a> and register</p></li>
<li><p>To set admin rights to the newly created account, use the following command line:</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>ftcli<span class="w"> </span>users<span class="w"> </span>update<span class="w"> </span>&lt;username&gt;<span class="w"> </span>--set-admin<span class="w"> </span><span class="nb">true</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If the user account is inactive, it activates it.</p>
</div>
</section>
<section id="from-sources">
<h3>From sources<a class="headerlink" href="#from-sources" title="Permalink to this heading"></a></h3>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<div class="line-block">
<div class="line">Since FitTrackee 0.2.1, Python packages installation needs Poetry.</div>
<div class="line">To install it on ArchLinux:</div>
</div>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>yay<span class="w"> </span>poetry
$<span class="w"> </span>poetry<span class="w"> </span>--version
Poetry<span class="w"> </span><span class="m">1</span>.0.17
<span class="c1"># optional</span>
$<span class="w"> </span>poetry<span class="w"> </span>config<span class="w"> </span>virtualenvs.in-project<span class="w"> </span><span class="nb">true</span>
</pre></div>
</div>
<p>For other OS, see <a class="reference external" href="https://python-poetry.org/docs/#installation">Poetry Documentation</a></p>
</div>
<section id="dev-environment">
<h4>Dev environment<a class="headerlink" href="#dev-environment" title="Permalink to this heading"></a></h4>
<ul class="simple">
<li><p>Clone this repo:</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>git<span class="w"> </span>clone<span class="w"> </span>https://github.com/SamR1/FitTrackee.git
$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>FitTrackee
</pre></div>
</div>
<ul class="simple">
<li><p>Create <strong>.env</strong> from example and update it
(see <a class="reference external" href="installation.html#environment-variables">Environment variables</a>).</p></li>
<li><p>Install Python virtualenv, Vue and all related packages and
initialize the database:</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>make<span class="w"> </span>install-dev
$<span class="w"> </span>make<span class="w"> </span>install-db
</pre></div>
</div>
<ul class="simple">
<li><p>Start the server and the client:</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>make<span class="w"> </span>serve
</pre></div>
</div>
<ul class="simple">
<li><p>Run dramatiq workers:</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>make<span class="w"> </span>run-workers
</pre></div>
</div>
<ul class="simple">
<li><p>Open <a class="reference external" href="http://localhost:3000">http://localhost:3000</a> and register</p></li>
<li><p>To set admin rights to the newly created account, use the following command line:</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>make<span class="w"> </span>user-set-admin<span class="w"> </span><span class="nv">USERNAME</span><span class="o">=</span>&lt;username&gt;
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If the user account is inactive, it activates it.</p>
</div>
</section>
<section id="production-environment">
<h4>Production environment<a class="headerlink" href="#production-environment" title="Permalink to this heading"></a></h4>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<div class="line-block">
<div class="line">Note that FitTrackee is under heavy development, some features may be unstable.</div>
</div>
</div>
<ul class="simple">
<li><p>Download the last release (for now, it is the release v0.7.15):</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>wget<span class="w"> </span>https://github.com/SamR1/FitTrackee/archive/v0.7.15.tar.gz
$<span class="w"> </span>tar<span class="w"> </span>-xzf<span class="w"> </span>v0.7.15.tar.gz
$<span class="w"> </span>mv<span class="w"> </span>FitTrackee-0.7.15<span class="w"> </span>FitTrackee
$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>FitTrackee
</pre></div>
</div>
<ul class="simple">
<li><p>Create <strong>.env</strong> from example and update it
(see <a class="reference external" href="installation.html#environment-variables">Environment variables</a>).</p></li>
<li><p>Install Python virtualenv and all related packages:</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>make<span class="w"> </span>install-python
</pre></div>
</div>
<ul class="simple">
<li><p>Initialize the database (<strong>after updating</strong> <code class="docutils literal notranslate"><span class="pre">db/create.sql</span></code> <strong>to change
database credentials</strong>):</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>make<span class="w"> </span>install-db
</pre></div>
</div>
<ul class="simple">
<li><p>Start the server and dramatiq workers:</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>make<span class="w"> </span>run
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If email sending is disabled: <code class="docutils literal notranslate"><span class="pre">$</span> <span class="pre">make</span> <span class="pre">run-server</span></code></p>
</div>
<ul class="simple">
<li><p>Open <a class="reference external" href="http://localhost:5000">http://localhost:5000</a> and register</p></li>
<li><p>To set admin rights to the newly created account, use the following command line:</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>make<span class="w"> </span>user-set-admin<span class="w"> </span><span class="nv">USERNAME</span><span class="o">=</span>&lt;username&gt;
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If the user account is inactive, it activates it.</p>
</div>
</section>
</section>
</section>
<section id="upgrade">
<h2>Upgrade<a class="headerlink" href="#upgrade" title="Permalink to this heading"></a></h2>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<div class="line-block">
<div class="line">Before upgrading, make a backup of all data:</div>
<div class="line">- database (with <a class="reference external" href="https://www.postgresql.org/docs/11/app-pgdump.html">pg_dump</a> for instance)</div>
<div class="line">- upload directory (see <a class="reference external" href="installation.html#environment-variables">Environment variables</a>)</div>
</div>
</div>
<section id="id3">
<h3>From PyPI<a class="headerlink" href="#id3" title="Permalink to this heading"></a></h3>
<ul class="simple">
<li><p>Stop the application and activate the virtualenv</p></li>
<li><p>Upgrade with pip</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>-U<span class="w"> </span>fittrackee
</pre></div>
</div>
<ul class="simple">
<li><p>Update environment variables if needed and source environment variables file</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>nano<span class="w"> </span>.env
$<span class="w"> </span><span class="nb">source</span><span class="w"> </span>.env
</pre></div>
</div>
<ul class="simple">
<li><p>Upgrade database if needed (see changelog for migrations):</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>ftcli<span class="w"> </span>db<span class="w"> </span>upgrade
</pre></div>
</div>
<ul class="simple">
<li><p>Restart the application and task queue workers (if email sending is enabled).</p></li>
</ul>
</section>
<section id="id4">
<h3>From sources<a class="headerlink" href="#id4" title="Permalink to this heading"></a></h3>
<section id="id5">
<h4>Dev environment<a class="headerlink" href="#id5" title="Permalink to this heading"></a></h4>
<ul class="simple">
<li><p>Stop the application and pull the repository:</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>git<span class="w"> </span>pull
</pre></div>
</div>
<ul class="simple">
<li><p>Update <strong>.env</strong> if needed (see <a class="reference external" href="installation.html#environment-variables">Environment variables</a>).</p></li>
<li><p>Upgrade packages:</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>make<span class="w"> </span>install-dev
</pre></div>
</div>
<ul class="simple">
<li><p>Upgrade database if needed (see changelog for migrations):</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>make<span class="w"> </span>upgrade-db
</pre></div>
</div>
<ul class="simple">
<li><p>Restart the server:</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>make<span class="w"> </span>serve
</pre></div>
</div>
<ul class="simple">
<li><p>Run dramatiq workers:</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>make<span class="w"> </span>run-workers
</pre></div>
</div>
</section>
<section id="prod-environment">
<h4>Prod environment<a class="headerlink" href="#prod-environment" title="Permalink to this heading"></a></h4>
<ul class="simple">
<li><p>Stop the application</p></li>
<li><p>Change to the directory where FitTrackee directory is located</p></li>
<li><p>Download the last release (for now, it is the release v0.7.15) and overwrite existing files:</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>wget<span class="w"> </span>https://github.com/SamR1/FitTrackee/archive/v0.7.15.tar.gz
$<span class="w"> </span>tar<span class="w"> </span>-xzf<span class="w"> </span>v0.7.15.tar.gz
$<span class="w"> </span>cp<span class="w"> </span>-R<span class="w"> </span>FitTrackee-0.7.15/*<span class="w"> </span>FitTrackee/
$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>FitTrackee
</pre></div>
</div>
<ul class="simple">
<li><p>Update <strong>.env</strong> if needed (see <a class="reference external" href="installation.html#environment-variables">Environment variables</a>).</p></li>
<li><p>Upgrade packages:</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>make<span class="w"> </span>install-dev
</pre></div>
</div>
<ul class="simple">
<li><p>Upgrade database if needed (see changelog for migrations):</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>make<span class="w"> </span>upgrade-db
</pre></div>
</div>
<ul class="simple">
<li><p>Restart the server and dramatiq workers:</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>make<span class="w"> </span>run
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If email sending is disabled: <code class="docutils literal notranslate"><span class="pre">$</span> <span class="pre">make</span> <span class="pre">run-server</span></code></p>
</div>
</section>
</section>
</section>
<section id="deployment">
<h2>Deployment<a class="headerlink" href="#deployment" title="Permalink to this heading"></a></h2>
<p>There are several ways to start <strong>FitTrackee</strong> web application and task queue
library.
One way is to use a <strong>systemd</strong> services and <strong>Nginx</strong> to proxy pass to <strong>Gunicorn</strong>.</p>
<p>Examples (to update depending on your application configuration and given distribution):</p>
<ul class="simple">
<li><p>for application: <code class="docutils literal notranslate"><span class="pre">fittrackee.service</span></code></p></li>
</ul>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">Unit</span><span class="p">]</span>
<span class="n">Description</span><span class="o">=</span><span class="n">FitTrackee</span> <span class="n">service</span>
<span class="n">After</span><span class="o">=</span><span class="n">network</span><span class="o">.</span><span class="n">target</span>
<span class="n">After</span><span class="o">=</span><span class="n">postgresql</span><span class="o">.</span><span class="n">service</span>
<span class="n">After</span><span class="o">=</span><span class="n">redis</span><span class="o">.</span><span class="n">service</span>
<span class="n">StartLimitIntervalSec</span><span class="o">=</span><span class="mi">0</span>
<span class="p">[</span><span class="n">Service</span><span class="p">]</span>
<span class="n">Type</span><span class="o">=</span><span class="n">simple</span>
<span class="n">Restart</span><span class="o">=</span><span class="n">always</span>
<span class="n">RestartSec</span><span class="o">=</span><span class="mi">1</span>
<span class="n">User</span><span class="o">=&lt;</span><span class="n">USER</span><span class="o">&gt;</span>
<span class="n">StandardOutput</span><span class="o">=</span><span class="n">syslog</span>
<span class="n">StandardError</span><span class="o">=</span><span class="n">syslog</span>
<span class="n">SyslogIdentifier</span><span class="o">=</span><span class="n">fittrackee</span>
<span class="n">Environment</span><span class="o">=</span><span class="s2">&quot;APP_SECRET_KEY=&quot;</span>
<span class="n">Environment</span><span class="o">=</span><span class="s2">&quot;APP_LOG=&quot;</span>
<span class="n">Environment</span><span class="o">=</span><span class="s2">&quot;UPLOAD_FOLDER=&quot;</span>
<span class="n">Environment</span><span class="o">=</span><span class="s2">&quot;DATABASE_URL=&quot;</span>
<span class="n">Environment</span><span class="o">=</span><span class="s2">&quot;UI_URL=&quot;</span>
<span class="n">Environment</span><span class="o">=</span><span class="s2">&quot;EMAIL_URL=&quot;</span>
<span class="n">Environment</span><span class="o">=</span><span class="s2">&quot;SENDER_EMAIL=&quot;</span>
<span class="n">Environment</span><span class="o">=</span><span class="s2">&quot;REDIS_URL=&quot;</span>
<span class="n">Environment</span><span class="o">=</span><span class="s2">&quot;TILE_SERVER_URL=&quot;</span>
<span class="n">Environment</span><span class="o">=</span><span class="s2">&quot;STATICMAP_SUBDOMAINS=&quot;</span>
<span class="n">Environment</span><span class="o">=</span><span class="s2">&quot;MAP_ATTRIBUTION=&quot;</span>
<span class="n">Environment</span><span class="o">=</span><span class="s2">&quot;WEATHER_API_KEY=&quot;</span>
<span class="n">WorkingDirectory</span><span class="o">=/</span><span class="n">home</span><span class="o">/&lt;</span><span class="n">USER</span><span class="o">&gt;/&lt;</span><span class="n">FITTRACKEE</span> <span class="n">DIRECTORY</span><span class="o">&gt;</span>
<span class="n">ExecStart</span><span class="o">=/</span><span class="n">home</span><span class="o">/&lt;</span><span class="n">USER</span><span class="o">&gt;/&lt;</span><span class="n">FITTRACKEE</span> <span class="n">DIRECTORY</span><span class="o">&gt;/.</span><span class="n">venv</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">gunicorn</span> <span class="o">-</span><span class="n">b</span> <span class="mf">127.0.0.1</span><span class="p">:</span><span class="mi">5000</span> <span class="s2">&quot;fittrackee:create_app()&quot;</span> <span class="o">--</span><span class="n">error</span><span class="o">-</span><span class="n">logfile</span> <span class="o">/</span><span class="n">home</span><span class="o">/&lt;</span><span class="n">USER</span><span class="o">&gt;/&lt;</span><span class="n">FITTRACKEE</span> <span class="n">DIRECTORY</span><span class="o">&gt;/</span><span class="n">gunicorn</span><span class="o">.</span><span class="n">log</span>
<span class="n">Restart</span><span class="o">=</span><span class="n">always</span>
<span class="p">[</span><span class="n">Install</span><span class="p">]</span>
<span class="n">WantedBy</span><span class="o">=</span><span class="n">multi</span><span class="o">-</span><span class="n">user</span><span class="o">.</span><span class="n">target</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>To handle large files, a higher value for <a class="reference external" href="https://docs.gunicorn.org/en/stable/settings.html#timeout">timeout</a> can be set.</p>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>More information on deployment with Gunicorn in its <a class="reference external" href="https://docs.gunicorn.org/en/stable/deploy.html">documentation</a>.</p>
</div>
<ul class="simple">
<li><p>for task queue workers: <code class="docutils literal notranslate"><span class="pre">fittrackee_workers.service</span></code></p></li>
</ul>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">Unit</span><span class="p">]</span>
<span class="n">Description</span><span class="o">=</span><span class="n">FitTrackee</span> <span class="n">task</span> <span class="n">queue</span> <span class="n">service</span>
<span class="n">After</span><span class="o">=</span><span class="n">network</span><span class="o">.</span><span class="n">target</span>
<span class="n">After</span><span class="o">=</span><span class="n">postgresql</span><span class="o">.</span><span class="n">service</span>
<span class="n">After</span><span class="o">=</span><span class="n">redis</span><span class="o">.</span><span class="n">service</span>
<span class="n">StartLimitIntervalSec</span><span class="o">=</span><span class="mi">0</span>
<span class="p">[</span><span class="n">Service</span><span class="p">]</span>
<span class="n">Type</span><span class="o">=</span><span class="n">simple</span>
<span class="n">Restart</span><span class="o">=</span><span class="n">always</span>
<span class="n">RestartSec</span><span class="o">=</span><span class="mi">1</span>
<span class="n">User</span><span class="o">=&lt;</span><span class="n">USER</span><span class="o">&gt;</span>
<span class="n">StandardOutput</span><span class="o">=</span><span class="n">syslog</span>
<span class="n">StandardError</span><span class="o">=</span><span class="n">syslog</span>
<span class="n">SyslogIdentifier</span><span class="o">=</span><span class="n">fittrackee_workers</span>
<span class="n">Environment</span><span class="o">=</span><span class="s2">&quot;FLASK_APP=fittrackee&quot;</span>
<span class="n">Environment</span><span class="o">=</span><span class="s2">&quot;APP_SECRET_KEY=&quot;</span>
<span class="n">Environment</span><span class="o">=</span><span class="s2">&quot;APP_LOG=&quot;</span>
<span class="n">Environment</span><span class="o">=</span><span class="s2">&quot;UPLOAD_FOLDER=&quot;</span>
<span class="n">Environment</span><span class="o">=</span><span class="s2">&quot;DATABASE_URL=&quot;</span>
<span class="n">Environment</span><span class="o">=</span><span class="s2">&quot;UI_URL=&quot;</span>
<span class="n">Environment</span><span class="o">=</span><span class="s2">&quot;EMAIL_URL=&quot;</span>
<span class="n">Environment</span><span class="o">=</span><span class="s2">&quot;SENDER_EMAIL=&quot;</span>
<span class="n">Environment</span><span class="o">=</span><span class="s2">&quot;REDIS_URL=&quot;</span>
<span class="n">WorkingDirectory</span><span class="o">=/</span><span class="n">home</span><span class="o">/&lt;</span><span class="n">USER</span><span class="o">&gt;/&lt;</span><span class="n">FITTRACKEE</span> <span class="n">DIRECTORY</span><span class="o">&gt;</span>
<span class="n">ExecStart</span><span class="o">=/</span><span class="n">home</span><span class="o">/&lt;</span><span class="n">USER</span><span class="o">&gt;/&lt;</span><span class="n">FITTRACKEE</span> <span class="n">DIRECTORY</span><span class="o">&gt;/.</span><span class="n">venv</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">flask</span> <span class="n">worker</span> <span class="o">--</span><span class="n">processes</span> <span class="o">&lt;</span><span class="n">NUMBER</span> <span class="n">OF</span> <span class="n">PROCESSES</span><span class="o">&gt;</span>
<span class="n">Restart</span><span class="o">=</span><span class="n">always</span>
<span class="p">[</span><span class="n">Install</span><span class="p">]</span>
<span class="n">WantedBy</span><span class="o">=</span><span class="n">multi</span><span class="o">-</span><span class="n">user</span><span class="o">.</span><span class="n">target</span>
</pre></div>
</div>
<ul class="simple">
<li><p><strong>Nginx</strong> configuration:</p></li>
</ul>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>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&#39;ll need to change this
## setting by uncommenting the line below and setting the size limit
## you want. Set to &quot;0&quot; 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;
}
}
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If needed, update configuration to handle larger files (see <a class="reference external" href="https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size">client_max_body_size</a>).</p>
</div>
</section>
<section id="docker">
<h2>Docker<a class="headerlink" href="#docker" title="Permalink to this heading"></a></h2>
<section id="id6">
<h3>Installation<a class="headerlink" href="#id6" title="Permalink to this heading"></a></h3>
<div class="versionadded">
<p><span class="versionmodified added">New in version 0.4.4.</span></p>
</div>
<p>For evaluation purposes, docker files are available, installing <strong>FitTrackee</strong> from <strong>sources</strong>.</p>
<ul class="simple">
<li><p>To install <strong>FitTrackee</strong>:</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>git<span class="w"> </span>clone<span class="w"> </span>https://github.com/SamR1/FitTrackee.git
$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>FitTrackee
$<span class="w"> </span>cp<span class="w"> </span>.env.docker<span class="w"> </span>.env
$<span class="w"> </span>make<span class="w"> </span>docker-build
</pre></div>
</div>
<ul class="simple">
<li><p>To initialise database:</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>make<span class="w"> </span>docker-init
</pre></div>
</div>
<ul class="simple">
<li><p>Open <a class="reference external" href="http://localhost:5000">http://localhost:5000</a> and register.</p></li>
</ul>
<p>Open <a class="reference external" href="http://localhost:8025">http://localhost:8025</a> to access <a class="reference external" href="https://github.com/mailhog/MailHog">MailHog interface</a> (email testing tool)</p>
<ul class="simple">
<li><p>To set admin rights to the newly created account, use the following command line:</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>make<span class="w"> </span>docker-set-admin<span class="w"> </span><span class="nv">USERNAME</span><span class="o">=</span>&lt;username&gt;
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If the user account is inactive, it activates it.</p>
</div>
<ul class="simple">
<li><p>To stop <strong>Fittrackee</strong>:</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>make<span class="w"> </span>docker-stop
</pre></div>
</div>
<ul class="simple">
<li><p>To start <strong>Fittrackee</strong> (application and dramatiq workers):</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>make<span class="w"> </span>docker-run-all
</pre></div>
</div>
<ul class="simple">
<li><p>To run shell inside <strong>Fittrackee</strong> container:</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>make<span class="w"> </span>docker-shell
</pre></div>
</div>
</section>
<section id="development">
<h3>Development<a class="headerlink" href="#development" title="Permalink to this heading"></a></h3>
<div class="versionadded">
<p><span class="versionmodified added">New in version 0.5.0.</span></p>
</div>
<ul class="simple">
<li><p>an additional step is needed to install <cite>fittrackee_client</cite></p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>make<span class="w"> </span>docker-build-client
</pre></div>
</div>
<ul class="simple">
<li><p>to start <strong>FitTrackee</strong> with client dev tools:</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>make<span class="w"> </span>docker-serve-client
</pre></div>
</div>
<p>Open <a class="reference external" href="http://localhost:3000">http://localhost:3000</a></p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Some environment variables need to be updated like <cite>UI_URL</cite></p>
</div>
<ul class="simple">
<li><p>to run lint or tests:</p></li>
</ul>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>make<span class="w"> </span>docker-lint-client<span class="w"> </span><span class="c1"># run lint on javascript files</span>
$<span class="w"> </span>make<span class="w"> </span>docker-test-client<span class="w"> </span><span class="c1"># run unit tests on Client</span>
$<span class="w"> </span>make<span class="w"> </span>docker-lint-python<span class="w"> </span><span class="c1"># run type check and lint on python files</span>
$<span class="w"> </span>make<span class="w"> </span>docker-test-python<span class="w"> </span><span class="c1"># run unit tests on API</span>
</pre></div>
</div>
</section>
</section>
<section id="yunohost">
<h2>Yunohost<a class="headerlink" href="#yunohost" title="Permalink to this heading"></a></h2>
<p>A package is available, see <a class="reference external" href="https://github.com/YunoHost-Apps/fittrackee_ynh">https://github.com/YunoHost-Apps/fittrackee_ynh</a>.</p>
</section>
</section>
</div>
</div>
</div>
<footer class="footer">
<div class="container">
<p class="pull-right">
<a href="#">Back to top</a>
</p>
<p>
&copy; Copyright 2018 - 2023, SamR1 <a rel="me" href="https://fosstodon.org/@FitTrackee"><i class="fa fa-mastodon" aria-hidden="true"></i></a>.
Last updated on Apr 12, 2023.<br/>
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 5.3.0.<br/>
</p>
</div>
</footer>
</body>
</html>