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

It is advised that you keep your Fietsboek installation in a separate `virtual
environment <https://virtualenv.pypa.io/en/latest/>`__. 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

.. code:: bash

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

.. code:: bash

    # Assuming that we are in the Fietsboek folder
    .venv/bin/pip install .
    # Alternatively
    .venv/bin/pip path/to/fietsboek/repository

Optionally, you can install ``lxml``, which provides a faster XML parser to
process the GPX files:

.. code:: bash

    .venv/bin/pip install lxml

Configuring Fietsboek
---------------------

Before you can run Fietsboek, you need to adjust your configuration. See
:doc:`configuration` for that.

Setting up the Database
-----------------------

Fietsboek uses `alembic <https://alembic.sqlalchemy.org/en/latest/>`__ to
manage the database scheme. To set up the initial database, run

.. code:: bash

    .venv/bin/alembic -c production.ini upgrade head

Adding an Administrator User
----------------------------

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

.. code:: bash

    .venv/bin/fietsctl -c production.ini useradd --admin

Running Fietsboek
-----------------

To run Fietsboek, simply run

.. code:: bash

    .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
    <https://httpd.apache.org/docs/current/howto/reverse_proxy.html>`__ or
    `nginx <https://nginx.org/en/docs/http/ngx_http_proxy_module.html>`__) 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 user's data at risk!

The default server uses `waitress
<https://docs.pylonsproject.org/projects/waitress/en/stable/index.html>`__ 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 <https://gunicorn.org/>`__ or
`mod_wsgi <https://modwsgi.readthedocs.io/en/master/>`__ for better
performance. For those, refer to the Pyramid documentation for more information:

* `gunicorn
  <https://docs.pylonsproject.org/projects/pyramid_cookbook/en/latest/deployment/gunicorn.html>`__
* `mod_wsgi
  <https://docs.pylonsproject.org/projects/pyramid/en/latest/tutorials/modwsgi/index.html>`__

Maintaining Fietsboek
---------------------

A good installation should be well-oiled, which means it should be
:doc:`updated <upgrading>` to new versions and :doc:`backups <backup>` should
be done frequently.