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.9 or later

  • A redis server, used for caching and temporary data

  • (Optionally) an SQL database server like PostgreSQL or MariaDB (if SQLite is not enough)

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 some of Fietsboek’s dependencies (such as pydantic and nh3) use Rust modules. If they don’t provide a binary wheel for your interpreter, they will automatically build one during the installation process — but that requires the Rust toolchain.

To install Rust, check out your distributions wiki/packages, or use the rustup tool.

Creating an Environment

It is advised that you keep your Fietsboek installation in a separate virtual environment. This makes sure that the dependencies that Fietsboek pulls in do not interfere with your system’s libraries, and it makes sure that you can upgrade those components easily without affecting other installed programs.

We will assume that you create your environment in the .venv folder. Any path can be choosen, you just need to remember it for later

# If Python 3 is the default on your system:
virtualenv .venv
# Otherwise:
virtualenv -p python3 .venv

Installing the Python Modules

The Python package manager takes care of installing all dependencies, all you need to do is tell it to install Fietsboek. How exactly depends on your way of acquiring Fietsboek.

Via PIP

Fietsboek is available in the Python Package Index as fietsboek and can be installed directly via pip:

.venv/bin/pip install fietsboek

Via Git

If you prefer to work with the source version (e.g. for development purposes), you should use Git to clone the repository from one of its mirrors:

git clone https://gitlab.com/dunj3/fietsboek
.venv/bin/pip install ./fietsboek
# For development, you can use -e for an editable installation:
.venv/bin/pip install -e ./fietsboek

Optional: Install lxml

In any case, you can optionally install lxml, which provides a faster XML parser to process the GPX files:

.venv/bin/pip install lxml

Note

It is currently unclear whether lxml does provide a speed benefit over the alternative, especially when running on PyPy. See also issue #7.

Configuring Fietsboek

Before you can run Fietsboek, you need to adjust your configuration. See Configuration for that.

Setting up the Database

Fietsboek users the fietsupdate script to handle database migrations and other update tasks. You can use it to set up the initial database schema:

.venv/bin/fietsupdate update -c production.ini

Note

If you install Fietsboek via Git, and you stick to the master branch instead of a specific version, you must also run .venv/bin/alembic -c production.ini upgrade head.

See The Updater (“Furhter notes”) for more information.

Adding an Administrator User

You can use the fietsctl command line program to add administrator users:

.venv/bin/fietsctl user add -c production.ini --admin

Running Fietsboek

To run Fietsboek, simply run

.venv/bin/pserve production.ini

Warning

It is strongly advised that you use a httpd configured with SSL as a reverse proxy (such as Apache2 or nginx) to handle external traffic to Fietsboek!

Fietsboek itself does not use SSL encryption for its traffic, and not setting up a proper reverse proxy will put your users’ data at risk!

The default server uses waitress and should be enough for small to medium traffic. It is implemented purely in Python and should run on most systems.

Alternatively, you can switch to gunicorn or mod_wsgi for better performance. For those, refer to the Pyramid documentation for more information:

Maintaining Fietsboek

A good installation should be well-oiled, which means it should be updated to new versions and backups should be done frequently.