update documentation
This commit is contained in:
Sam
parent
a15e36de51
commit
ff93b97d3c
@ -10,6 +10,7 @@ This application is written in Python (API) and Typescript (client):
|
||||
- `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
|
||||
- `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
|
||||
@ -21,13 +22,16 @@ This application is written in Python (API) and Typescript (client):
|
||||
Prerequisites
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
- Python 3.7+
|
||||
- PostgreSQL database (10+)
|
||||
- SMTP provider and Redis for task queue (if email sending is enabled)
|
||||
- API key from `Dark Sky <https://darksky.net/dev>`__ (not mandatory)
|
||||
- `Poetry <https://poetry.eustace.io>`__ (for installation from sources only)
|
||||
- `Yarn <https://yarnpkg.com>`__ (for development only)
|
||||
- Docker and Docker Compose (for development or evaluation purposes)
|
||||
- mandatory
|
||||
- Python 3.7+
|
||||
- PostgreSQL 10+
|
||||
- optional
|
||||
- Redis for task queue (if email sending is enabled) and API rate limits
|
||||
- SMTP provider (if email sending is enabled)
|
||||
- API key from `Dark Sky <https://darksky.net/dev>`__
|
||||
- `Poetry <https://poetry.eustace.io>`__ (for installation from sources only)
|
||||
- `Yarn <https://yarnpkg.com>`__ (for development only)
|
||||
- Docker and Docker Compose (for development or evaluation purposes)
|
||||
|
||||
.. note::
|
||||
| The following steps describe an installation on Linux systems (tested
|
||||
@ -156,7 +160,7 @@ deployment method.
|
||||
|
||||
.. versionadded:: 0.3.0
|
||||
|
||||
Redis instance used by **Dramatiq**.
|
||||
Redis instance used by **Dramatiq** and **Flask-Limiter**.
|
||||
|
||||
:default: local Redis instance (``redis://``)
|
||||
|
||||
@ -168,6 +172,15 @@ deployment method.
|
||||
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
|
||||
@ -178,7 +191,7 @@ deployment method.
|
||||
:default: `https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png`
|
||||
|
||||
|
||||
.. envvar:: STATICMAP_SUBDOMAINS 🆕
|
||||
.. envvar:: STATICMAP_SUBDOMAINS
|
||||
|
||||
.. versionadded:: 0.6.10
|
||||
|
||||
@ -289,6 +302,42 @@ For instance, to set OSM France tile server, the expected values are:
|
||||
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
|
||||
|
||||
|
||||
Installation
|
||||
~~~~~~~~~~~~
|
||||
|
||||
|
||||
@ -124,6 +124,8 @@
|
||||
environment variable
|
||||
|
||||
<ul>
|
||||
<li><a href="installation.html#envvar-API_RATE_LIMITS">API_RATE_LIMITS 🆕</a>
|
||||
</li>
|
||||
<li><a href="installation.html#envvar-APP_LOG">APP_LOG</a>
|
||||
</li>
|
||||
<li><a href="installation.html#envvar-APP_SECRET_KEY">APP_SECRET_KEY</a>
|
||||
@ -152,7 +154,7 @@
|
||||
</li>
|
||||
<li><a href="installation.html#envvar-SENDER_EMAIL">SENDER_EMAIL</a>
|
||||
</li>
|
||||
<li><a href="installation.html#envvar-STATICMAP_SUBDOMAINS">STATICMAP_SUBDOMAINS 🆕</a>
|
||||
<li><a href="installation.html#envvar-STATICMAP_SUBDOMAINS">STATICMAP_SUBDOMAINS</a>
|
||||
</li>
|
||||
<li><a href="installation.html#envvar-TILE_SERVER_URL">TILE_SERVER_URL</a>
|
||||
</li>
|
||||
|
||||
@ -85,9 +85,10 @@
|
||||
<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>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#id1">Installation</a><ul>
|
||||
<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>
|
||||
@ -97,9 +98,9 @@
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#upgrade">Upgrade</a><ul>
|
||||
<li><a class="reference internal" href="#id2">From PyPI</a></li>
|
||||
<li><a class="reference internal" href="#id3">From sources</a><ul>
|
||||
<li><a class="reference internal" href="#id4">Dev environment</a></li>
|
||||
<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>
|
||||
@ -107,7 +108,7 @@
|
||||
</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="#id5">Installation</a></li>
|
||||
<li><a class="reference internal" href="#id6">Installation</a></li>
|
||||
<li><a class="reference internal" href="#development">Development</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
@ -172,6 +173,7 @@
|
||||
<li><p><a class="reference external" href="https://github.com/ZeevG/python-forecast.io">python-forecast.io</a> to fetch weather data from <a class="reference external" href="https://darksky.net">Dark Sky</a> (former forecast.io)</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>
|
||||
@ -193,14 +195,27 @@
|
||||
<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 database (10+)</p></li>
|
||||
<li><p>SMTP provider and Redis for task queue (if email sending is enabled)</p></li>
|
||||
<li><p>API key from <a class="reference external" href="https://darksky.net/dev">Dark Sky</a> (not mandatory)</p></li>
|
||||
<li><p>PostgreSQL 10+</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 API rate limits</p></li>
|
||||
<li><p>SMTP provider (if email sending is enabled)</p></li>
|
||||
<li><p>API key from <a class="reference external" href="https://darksky.net/dev">Dark Sky</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">
|
||||
@ -392,7 +407,7 @@ see <a class="reference external" href="https://docs.sqlalchemy.org/en/13/core/p
|
||||
<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>.</p>
|
||||
<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>
|
||||
@ -409,6 +424,20 @@ see <a class="reference external" href="https://docs.sqlalchemy.org/en/13/core/p
|
||||
<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 class="pre">🆕</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>
|
||||
@ -428,7 +457,7 @@ see <a class="reference external" href="https://docs.sqlalchemy.org/en/13/core/p
|
||||
|
||||
<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 class="pre">🆕</span></span><a class="headerlink" href="#envvar-STATICMAP_SUBDOMAINS" title="Permalink to this definition">¶</a></dt>
|
||||
<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>
|
||||
@ -572,9 +601,48 @@ The tile server can be changed by updating <code class="docutils literal notrans
|
||||
</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">"200 per day, 50 per hour"</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>$ flask limiter
|
||||
Usage: flask limiter <span class="o">[</span>OPTIONS<span class="o">]</span> COMMAND <span class="o">[</span>ARGS<span class="o">]</span>...
|
||||
|
||||
Flask-Limiter maintenance <span class="p">&</span> utility commmands
|
||||
|
||||
Options:
|
||||
--help Show this message and exit.
|
||||
|
||||
Commands:
|
||||
clear Clear limits <span class="k">for</span> a specific key
|
||||
config View the extension configuration
|
||||
limits Enumerate details about all routes with rate limits
|
||||
</pre></div>
|
||||
</div>
|
||||
</section>
|
||||
<section id="id1">
|
||||
<h2>Installation<a class="headerlink" href="#id1" title="Permalink to this heading">¶</a></h2>
|
||||
</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">
|
||||
@ -776,8 +844,8 @@ database credentials</strong>):</p></li>
|
||||
<div class="line">- upload directory (see <a class="reference external" href="installation.html#environment-variables">Environment variables</a>)</div>
|
||||
</div>
|
||||
</div>
|
||||
<section id="id2">
|
||||
<h3>From PyPI<a class="headerlink" href="#id2" title="Permalink to this heading">¶</a></h3>
|
||||
<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>
|
||||
@ -802,10 +870,10 @@ $ <span class="nb">source</span> .env
|
||||
<li><p>Restart the application and task queue workers (if email sending is enabled).</p></li>
|
||||
</ul>
|
||||
</section>
|
||||
<section id="id3">
|
||||
<h3>From sources<a class="headerlink" href="#id3" title="Permalink to this heading">¶</a></h3>
|
||||
<section id="id4">
|
||||
<h4>Dev environment<a class="headerlink" href="#id4" title="Permalink to this heading">¶</a></h4>
|
||||
<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>
|
||||
@ -996,8 +1064,8 @@ server {
|
||||
</section>
|
||||
<section id="docker">
|
||||
<h2>Docker<a class="headerlink" href="#docker" title="Permalink to this heading">¶</a></h2>
|
||||
<section id="id5">
|
||||
<h3>Installation<a class="headerlink" href="#id5" title="Permalink to this heading">¶</a></h3>
|
||||
<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>
|
||||
|
||||
BIN
docs/objects.inv
BIN
docs/objects.inv
Binary file not shown.
File diff suppressed because one or more lines are too long
Loading…
Reference in New Issue
Block a user