diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/administration/configuration.rst | 43 | ||||
| -rw-r--r-- | doc/administration/docker.rst | 33 | ||||
| -rw-r--r-- | doc/administration/installation.rst | 38 | ||||
| -rw-r--r-- | doc/developer/module/hittekaart_py.rst | 168 | ||||
| -rw-r--r-- | doc/developer/module/modules.rst | 8 | ||||
| -rw-r--r-- | doc/man/fietsctl.rst | 22 |
6 files changed, 279 insertions, 33 deletions
diff --git a/doc/administration/configuration.rst b/doc/administration/configuration.rst index 24c5fdb..99ce4d1 100644 --- a/doc/administration/configuration.rst +++ b/doc/administration/configuration.rst @@ -218,18 +218,44 @@ true``. This will cause the tiles to be loaded directly by the client. your users that third party content is included in your site, and that their IP will be accessible to the third party. +Overpass API +------------ + +Fietsboek uses Overpass_ to name climbs. You can set custom Overpass instances +in the config: + +.. code:: ini + + overpass.url = https://overpass.example.com/api/interpreter + # HTTP Basic auth, if needed: + overpass.basic_auth.username = fietsboek + overpass.basic_auth.password = super5ecre7 + +By default, Fietsboek uses the API instance at +https://maps.mail.ru/osm/tools/overpass/api/interpreter, however, it is often +overloaded and will respond with timeouts. + +.. note:: + + The URL needs to include the whole path to the interpreter script, so + usually it ends with ``/api/interpreter``. + +.. note:: + + Overpass has no standard way to do authentication. Commonly, the API key is + included in the URL. Fietsboek also has support for HTTP Basic auth. + +.. _Overpass: https://wiki.openstreetmap.org/wiki/Overpass_API + Hittekaart Integration ---------------------- -Fietsboek can use hittekaart_ to generate heat maps for users. For that, you -can set ``hittekaart.bin`` to the path to the ``hittekaart`` binary. If unset, -it is assumed that the binary can be found in your ``$PATH``. +Fietsboek can use hittekaart_ to generate heat maps for users. -In addition, you can set ``hittekaart.autogenerate`` to the list of overlay -maps you want to automatically generate and update. By default, this list is -empty, which means that Fietsboek will not generate any overlays on its own. -You can add ``heatmap`` and/or ``tilehunter`` to generate those maps -automatically. +You can set ``hittekaart.autogenerate`` to the list of overlay maps you want to +automatically generate and update. By default, this list is empty, which means +that Fietsboek will not generate any overlays on its own. You can add +``heatmap`` and/or ``tilehunter`` to generate those maps automatically. By default, ``hittekaart`` will use as many threads as CPU cores are available. This leads to the fastest heatmap generation, but might be undesired on shared @@ -253,7 +279,6 @@ An example configuration excerpt can look like this: .. code-block:: ini - hittekaart.bin = /usr/local/bin/hittekaart hittekaart.autogenerate = heatmap tilehunter hittekaart.threads = 2 diff --git a/doc/administration/docker.rst b/doc/administration/docker.rst index ed44a05..b5df268 100644 --- a/doc/administration/docker.rst +++ b/doc/administration/docker.rst @@ -68,21 +68,24 @@ the options that diverge from the default values:: The following environment variables are supported: -=============================== =============================== -Environment variable Setting -=============================== =============================== -``REDIS_URL`` [#f1]_ ``redis.url`` -``SQLALCHEMY_URL`` ``sqlalchemy.url`` -``DATA_DIR`` ``fietsboek.data_dir`` -``SESSION_KEY`` [#f2]_ ``session_key`` -``ENABLE_ACCOUNT_REGISTRATION`` ``enable_account_registration`` -``DEFAULT_LOCALE_NAME`` ``pyramid.default_locale_name`` -``EMAIL_FROM`` ``email.from`` -``EMAIL_SMTP_URL`` ``email.smtp_url`` -``EMAIL_USERNAME`` ``email.username`` -``EMAIL_PASSWORD`` ``email.password`` -``LOGLEVEL`` ``[logger_fietsboek] level`` -=============================== =============================== +================================ ================================ +Environment variable Setting +================================ ================================ +``REDIS_URL`` [#f1]_ ``redis.url`` +``SQLALCHEMY_URL`` ``sqlalchemy.url`` +``DATA_DIR`` ``fietsboek.data_dir`` +``SESSION_KEY`` [#f2]_ ``session_key`` +``ENABLE_ACCOUNT_REGISTRATION`` ``enable_account_registration`` +``DEFAULT_LOCALE_NAME`` ``pyramid.default_locale_name`` +``EMAIL_FROM`` ``email.from`` +``EMAIL_SMTP_URL`` ``email.smtp_url`` +``EMAIL_USERNAME`` ``email.username`` +``EMAIL_PASSWORD`` ``email.password`` +``OVERPASS_URL`` ``overpass.url`` +``OVERPASS_BASIC_AUTH_USERNAME`` ``overpass.basic_auth.username`` +``OVERPASS_BASIC_AUTH_PASSWORD`` ``overpass.basic_auth.password`` +``LOGLEVEL`` ``[logger_fietsboek] level`` +================================ ================================ .. [#f1] Required. .. [#f2] Defaults to a random string. diff --git a/doc/administration/installation.rst b/doc/administration/installation.rst index b207784..8c9c26e 100644 --- a/doc/administration/installation.rst +++ b/doc/administration/installation.rst @@ -6,14 +6,17 @@ This document will outline the installation process of Fietsboek, step-by-step. Requirements ------------ -Fietsboek has the following requirements (apart from the Python modules, which -will be installed by ``pip``): +Fietsboek has the following requirements: -* Python 3.10 or later -* A `redis <https://redis.com/>`__ server, used for caching and temporary data -* (Optionally) an SQL database server like `PostgreSQL - <https://www.postgresql.org/>`__ or `MariaDB <https://mariadb.org/>`__ (if - SQLite is not enough) +* A Linux system +* Python 3.11 or later +* A `redis <https://redis.com/>`__ server +* (Optionally) an SQL database server: + + * `PostgreSQL <https://www.postgresql.org/>`__ + +Other systems (such as BSD as operating system, or MariaDB as SQL server) might +work, but are not tested. In addition, if you run on a different interpreter than CPython, you might need a working Rust toolchain (``rustc`` and ``cargo``) installed. This is because @@ -97,6 +100,18 @@ parser to process the GPX files: .. _issue #7: https://gitlab.com/dunj3/fietsboek/-/issues/7 +Optional: Install Database Drivers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you decide to use a database other than SQLite, you must install the +required drivers: + +**PostgreSQL**: + +.. code:: bash + + .venv/bin/pip install psycopg2 + Configuring Fietsboek --------------------- @@ -119,7 +134,7 @@ other update tasks. You can use it to set up the initial database schema: instead of a specific version, you must also run ``.venv/bin/alembic -c production.ini upgrade head``. - See :doc:`../developer/updater` ("Furhter notes") for more information. + See :doc:`../developer/updater` ("Further notes") for more information. Adding an Administrator User ---------------------------- @@ -164,6 +179,13 @@ performance. For those, refer to the Pyramid documentation for more information: * `mod_wsgi <https://docs.pylonsproject.org/projects/pyramid/en/latest/tutorials/modwsgi/index.html>`__ +.. note:: + + When you use ``gunicorn``, make sure to set ``forward_allow_ips`` properly. + This also applies to ``gunicorn`` in the Docker container: + + https://gunicorn.org/reference/settings/#forwarded_allow_ips + Maintaining Fietsboek --------------------- diff --git a/doc/developer/module/hittekaart_py.rst b/doc/developer/module/hittekaart_py.rst new file mode 100644 index 0000000..f665799 --- /dev/null +++ b/doc/developer/module/hittekaart_py.rst @@ -0,0 +1,168 @@ +hittekaart_py package +===================== + +.. module:: hittekaart_py + + The ``hittekaart_py`` module provides a Python interface for hittekaart__ + heatmap generation. Unlike previous modules, this is a binding using + PyO3__, and not a subprocess wrapper. + +.. __: https://gitlab.com/dunj3/hittekaart +.. __: https://crates.io/crates/pyo3 + +Example +------- + +.. code-block:: python + + from hittekaart_py import ( + Track, HeatmapRenderer, Settings, Storage, generate + ) + + settings = Settings(threads=3) + tracks = [ + Track.from_file(b"Documents/track.gpx", None), + Track.from_coordinates([(45.0, 47.0)]), + ] + storage = Storage.OsmAnd(b"/tmp/tiles.sqlite") + generate(settings, tracks, HeatmapRenderer(), storage) + +Input and output +---------------- + +.. class:: Track + + An in-memory representation of a track. + + .. staticmethod:: from_file(path, compression) + + Loads a track from the given file. + + :param path: Path to the file. + :type path: bytes + :param compression: Decompression algorithm to use when reading the + file. Can be :obj:`None`, ``"gzip"`` or ``"brotli"``. + :type compression: str | None + :return: The created track. + :rtype: Track + + .. staticmethod:: from_coordinates(coordinates) + + Directly represents the given coordinates as a track. + + :param coordinates: The coordinates as a list of longitude-latitude + pairs. + :type coordinates: list[tuple[float, float]] + :return: The created track. + :rtype: Track + + +.. class:: Storage + + Represents the output storage. + + .. staticmethod:: Folder(path) + + Output the tiles to the given folder. This will create a subdirectory + for every zoom level, then a directory for the x coordinate, then a + file ``y.png``. + + Note that this will create many small files, which can waste space. + + :param path: Path to the folder. + :type path: bytes + :return: The created storage. + :rtype: Storage + + .. staticmethod:: OsmAnd(path) + + Output the tiles to the given SQLite database. The table format is + compatible with OsmAnd. See `the Rust crate`__ for more information. + + :param path: Path to the database. + :type path: bytes + :return: The created storage. + :rtype: Storage + + .. staticmethod:: MbTiles(path, name, description) + + Output the tiles to the given MbTiles database. Optionally, sets the + ``name`` and ``description`` metadata as given. See `the Rust crate`__ + for more information about the format. + + :param path: Path to the database. + :type path: bytes + :param name: Name of the resulting map layer. + :type name: str | None + :param description: Description of the map layer. + :type description: str | None + :return: The created storage. + :rtype: Storage + +.. __: https://docs.rs/hittekaart/latest/hittekaart/storage/struct.OsmAnd.html +.. __: https://docs.rs/hittekaart/latest/hittekaart/storage/struct.MbTiles.html + +Renderers +--------- + +.. class:: HeatmapRenderer() + + The renderer that generates a heatmap. + +.. class:: MarktileRenderer() + + The renderer that will only mark visited tiles. + +.. class:: TilehuntRenderer(zoom) + + The renderer that will mark visisted tiles at a fixed zoom level. + + :param zoom: The zoom level. + :type zoom: int + +Tile generation +--------------- + +.. class:: Settings(min_zoom=1, max_zoom=19, threads=0) + + Settings that apply to all renderers. + + .. attribute:: min_zoom + :type: int + + Smalles zoom level to generate tiles for. + + .. attribute:: max_zoom + :type: int + + Largest zoom level to generate tiles for. + + .. attribute:: threads + :type: int + + Number of threads to use for tile generation. + + Setting this to 0 will automatically determine the number of available + cores and use that many threads. + +.. function:: generate(settings, items, renderer, storage) + + Generates the tiles using the given renderer, and saves them to the given + storage. + + :param settings: The settings. + :type settings: Settings + :param items: The tracks to render. + :type items: ~typing.Iterable[Track] + :param renderer: The renderer to use. + :type renderer: HeatmapRenderer | MarktileRenderer | TilehuntRenderer + :param storage: The storage to output to. + :type storage: Storage + +Errors +------ + +.. exception:: HitteError + + Catch-all error for underlying hittekaart errors. See the string + description for the error cause. diff --git a/doc/developer/module/modules.rst b/doc/developer/module/modules.rst new file mode 100644 index 0000000..9585a5f --- /dev/null +++ b/doc/developer/module/modules.rst @@ -0,0 +1,8 @@ +fietsboek +========= + +.. toctree:: + :maxdepth: 1 + + fietsboek + hittekaart_py diff --git a/doc/man/fietsctl.rst b/doc/man/fietsctl.rst index 1d30b20..eb3dfae 100644 --- a/doc/man/fietsctl.rst +++ b/doc/man/fietsctl.rst @@ -11,7 +11,7 @@ SYNPOSIS .. code-block:: text fietsctl maintenance-mode - fietsctl track {del|list} + fietsctl track {add|del|list} fietsctl user {add|del|hittekaart|list|modify|passwd} fietsctl version @@ -186,6 +186,26 @@ For each track, the following information is shown: * The track's owner (both name and email address) * The track's title. +ADDING A TRACK +############## + +.. code-block:: text + + fietsctl track add [-c CONFIG] [-i/--id ID] [-e/--email] [--visibility PRIVATE|FRIENDS|FRIENDS_TAGGED|LOGGED_IN|PUBLIC] [--track-type ORGANIC|SYNTHETIC] FILENAME... + +Adds a track to the system. You specify the owner via the ``--id`` or +``--email`` options, similar to the ``user modify`` command. + +One or multiple ``FILENAME`` might be given. Any supported input format may be +used. + +The titles and dates are attempted to be read from the files. Other metadata +(tags, images, ...) is left empty. The ``--visibility`` and ``--track-type`` +options can be used to set the visibility and type of the added tracks. + +For each file read, the resulting ID in the database is printed. If an error +occurs for one file, the error is shown and the next track is read. + REMOVING A TRACK ################ |
