add docs for more tile proxy information

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
 -----------------------