Configuration

The main configuration of Fietsboek is done via .ini-files. By default, three such files exist:

  • production.ini contains the configuration for the production environment. It turns off debugging features (as they are a security risk!) and should contain the URL of the production database. This is the main file you want to use if you just want to deploy Fietsboek.

  • development.ini contains the configuration for local development on Fietsboek. This should not be used for production purposes, as it provides debugging information that poses a security risk!

  • testing.ini contains the configuration that the automated tests will use.

Most of the configuration is in the [app:main] category and looks like this:

[app:main]
use = egg:fietsboek

pyramid.reload_templates = false
pyramid.debug_authorization = false
pyramid.debug_notfound = false
pyramid.debug_routematch = false
pyramid.default_locale_name = en

email.from = fietsboek@localhost
email.smtp_url = debug://localhost:1025

available_locales = en de
enable_account_registration = true

session_key = <EDIT THIS>

sqlalchemy.url = sqlite:///%(here)s/fietsboek.sqlite
fietsboek.data_dir = %(here)s/data
redis.url = redis://localhost/

retry.attempts = 3

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

Fietsboek also allows you to install “language packs”, providing languages from third-party sources. Language packs are normal Python packages that must be installed via the package manager (e.g. by using pip in the same environment that you installed Fietsboek in), and then their names can be listed as fietsboek.language_packs in the configuration. Note that you must still add the locales to available_locales for them to work.

Warning

Since language packs are just Python packages, they can contain and execute arbitrary code. Do not install untrusted language packs.

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

As well as the following overlay layers:

You can use fietsboek.default_tile_layers to set the list of activated layers (by default, all of them), for example:

fietsboek.default_tile_layers = osm osmde cycling

You can enable Thunderforest 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:

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

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.