diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/administration/configuration.rst | 197 | ||||
| -rw-r--r-- | doc/administration/installation.rst | 12 |
2 files changed, 167 insertions, 42 deletions
diff --git a/doc/administration/configuration.rst b/doc/administration/configuration.rst index 5268903..feb3e40 100644 --- a/doc/administration/configuration.rst +++ b/doc/administration/configuration.rst @@ -36,51 +36,164 @@ Most of the configuration is in the ``[app:main]`` category and looks like this: sqlalchemy.url = sqlite:///%(here)s/fietsboek.sqlite fietsboek.data_dir = %(here)s/data + redis.url = redis://localhost/ retry.attempts = 3 -* You should leave the ``use``, ``pyramid.reload_templates`` and - ``pyramid.debug_*`` settings as they are. -* ``pyramid.default_locale_name`` can be used to set the default language of - the installation. Note that Fietsboek will try to detect the user's language, - so the ``default_locale_name`` is used as a fallback. -* ``available_locales`` sets the list of available languages. Currently, - Fietsboek ships with English ("en") and German ("de"). Removing a language - from this list will make it unavailable. If you create a custom language - locally, make sure to add it to this list here! -* ``enable_account_registration`` can be used to enable and disable the - creation of new accounts via the web interface, for example if you want to - have a private instance. New accounts can always be created using the CLI - management tool. -* ``session_key`` should be set to a random string of characters. This is the - key used to sign session data, so it should not get into wrong hands! -* ``sqlalchemy.url`` is the URL to the database. See the `SQLAlchemy - documentation - <https://docs.sqlalchemy.org/en/14/core/engines.html#database-urls>`__ for - more information. -* ``fietsboek.data_dir`` sets the directory for data uploads. This directory - must be writable by the Fietsboek process, as Fietsboek will save track - images in there. -* ``fietsboek.pages`` see :doc:`custom-pages`. -* ``email.from`` sets the sender of emails, for example for account verifications. -* ``email.smtp_url`` sets the URL of the SMTP server. The following formats are accepted: - - * ``debug://`` a debug implementation that simply prints emails to the - standard output. Should not be used in production, as no emails would ever - arrive. - * ``smtp://host:port`` use the given SMTP server (without transport encryption!) - * ``smtp+ssl://host:port`` use the given SMTP server over a SSL connection - * ``smtp+starttls://host:port`` use the given SMTP server and the STARTTLS - command to start an encrypted channel. - -* ``email.username`` and ``email.password`` can be used to set the login - information for the SMTP server. -* ``thunderforest.api_key`` can be set to an API key of `Thunderforest - <https://www.thunderforest.com/>`__ to enable support for the OpenCycleMap, - Landscape and Outdoors maps. +General Settings +---------------- +Use ``enable_account_registration`` enable or disable the creation of new +accounts via the web interface, for example if you want to have a private +instance. New accounts can always be created using the CLI management tool. + +Set ``session_key`` to a random string of characters. This is the key used to +sign session data, so it should not get into wrong hands! + +You can set up custom pages using ``fietsboek.pages``. See :doc:`custom-pages` +for more information. + +Pyramid Settings +---------------- + +You should leave the ``use``, ``pyramid.reload_templates`` and +``pyramid.debug_*`` settings as they are. Refer to the `Pyramid documentation +<https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html>`__ +for more information. + +Language Settings +----------------- + +You can set the default language with the ``pyramid.default_locale_name`` +setting. Note that Fietsboek will try to detect the user's language, so the +``default_locale_name`` is used as a fallback. + +You can use ``available_locales`` to set the list of available languages. +Currently, Fietsboek ships with English ("en") and German ("de"). Removing a +language from this list will make it unavailable. If you create a custom +language locally, make sure to add it to this list here! + +Database Settings +----------------- + +Fietsboek uses three different databases: +A SQL database for persistent data (like user accounts), a file storage on the +disk for big files (like images), and a redis server for ephemeral data (like +cached tiles). + +Set ``sqlalchemy.url`` to the URL of the SQL database. See the `SQLAlchemy +documentation +<https://docs.sqlalchemy.org/en/14/core/engines.html#database-urls>`__ for more +information on available URL formats. Make sure to install the driver necessary +to communicate with your database (e.g. ``psycopg2`` for PostreSQL)! + +Set ``fietsboek.data_dir`` to the directory for data uploads. This directory +must be writable by the Fietsboek process, as Fietsboek will save track images +in there. + +Set ``redis.url`` to the URL of the redis instance. See the `redis module +documentation +<https://redis.readthedocs.io/en/latest/connections.html#redis.Redis.from_url>`__ +for information about the possible syntaxes of this URL. Note that the redis +server is only used for caching and temporary data, so don't sweat to make it +persistent. A container running redis is fine. + +.. note:: + + Fietsboek will cache map tiles in the redis server. + To avoid using up too much memory, consider setting a maximum memory size + and policy in redis: + + https://redis.io/docs/management/config/#configuring-redis-as-a-cache + +Email Settings +-------------- + +Use ``email.from`` to set the sender of emails, for example for account verifications. + +Set ``email.smtp_url`` to the URL of the SMTP server. The following formats are +accepted: + +* ``debug://`` a debug implementation that simply prints emails to the + standard output. Should not be used in production, as no emails would ever + arrive. +* ``smtp://host:port`` use the given SMTP server (without transport encryption!) +* ``smtp+ssl://host:port`` use the given SMTP server over a SSL connection +* ``smtp+starttls://host:port`` use the given SMTP server and the STARTTLS + command to start an encrypted channel. + +Use ``email.username`` and ``email.password`` to set the login credentials for +the SMTP server. + +Map Layers & Thunderforest Integration +-------------------------------------- + +By default, Fietsboek offers the following map layers: + +* ``osm``: `OpenStreetMap <https://www.openstreetmap.org>`__ +* ``osmde``: `OpenStreetMap Deutschland <https://www.openstreetmap.de/>`__ +* ``satellite``: Satellite imaging from `Esri <https://www.esri.com>`__ +* ``opentopo``: `OpenTopoMap <https://opentopomap.org/>`__ +* ``topplusopen``: `TopPlus-Open + <https://www.bkg.bund.de/SharedDocs/Produktinformationen/BKG/EN/P-2017/171114-TopPlus-Web-Open.html>`__ + +As well as the following overlay layers: + +* ``opensea``: `OpenSeaMap <https://openseamap.org>`__ +* ``cycling``: `Waymarked Trails: Cycling <https://cycling.waymarkedtrails.org>`__ +* ``hiking``: `Waymarked Trails: Hiking <https://hiking.waymarkedtrails.org/>`__ + +You can use ``fietsboek.default_tile_layers`` to set the list of activated +layers (by default, all of them), for example: + +.. code:: ini + + fietsboek.default_tile_layers = osm osmde cycling + +You can enable `Thunderforest <https://www.thunderforest.com>`__ support by +setting ``thunderforest.api_key``, and ``thunderforest.maps`` to a list of +Thunderforest maps (e.g. "cycle" or "landscape"). By default, only logged in +users will be able to use the Thunderforest maps (to protect your quota), this +can be changed by setting ``thunderforest.access = public`` (default is +"restricted"). + +You can add custom tile layers in the following way: + +.. code:: ini + + fietsboek.tile_layer.ID = My Custom Layer + fietsboek.tile_layer.ID.url = https://tiles.example.com/{z}/{x}/{y}.png + # Optional, set the type (base or overlay), default base + fietsboek.tile_layer.ID.type = base + # Optional, set the maximum zoom factor, default 22 + fietsboek.tile_layer.ID.zoom = 22 + # Optional, set the attribution + fietsboek.tile_layer.ID.attribution = Copyright Example + # Optional, set the access restriction (public or restricted), default + # public + fietsboek.tile_layer.ID.access = public + +``ID`` must be an alphanumerical identifier. + +By default, Fietsboek will proxy all tile requests through the Fietsboek +instance. While this can slow down the user experience, it has the following +benefits: + +* Your users' IPs stay private and protected, as no third party is contacted. + The tile servers will only see the IP from the Fietsboek server. +* If you use private tile servers or servers that require a key, your key is + protected as it will not be given out to the users. +* Fietsboek caches tile requests, which reduces the strain on the providers and + might even make maps faster if many people use them. + +You can disable the tile proxy by setting ``fietsboek.tile_proxy.disable = +true``. This will cause the tiles to be loaded directly by the client. .. warning:: - The API key will be embedded in the source of the website, therefore it is - possible for visitors to "steal" the API key. Keep that in mind when - setting an API key for a publicly accessible site! + If you disable the tile proxy, all tile source URLs will be given to the + user. If you use API keys or other private sources, **those keys will be + leaked to the users**. + + In addition, depending on the jurisdiction, you might be required to tell + your users that third party content is included in your site, and that + their IP will be accessible to the third party. diff --git a/doc/administration/installation.rst b/doc/administration/installation.rst index b8ede06..4af0941 100644 --- a/doc/administration/installation.rst +++ b/doc/administration/installation.rst @@ -3,6 +3,18 @@ Installation 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``): + +* Python 3.7 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) + Creating an Environment ----------------------- |