add documentation about Docker

2 files changed, 160 insertions, 0 deletions

diff --git a/doc/administration.rst b/doc/administration.rst
index 6cf0f52..e09258b 100644
--- a/doc/administration.rst
+++ b/doc/administration.rst
@@ -12,6 +12,7 @@ Administration Guide
     administration/cronjobs
     administration/custom-pages
     administration/maintenance-mode
+    administration/docker
 
 This guide contains information pertaining to the administration of a Fietsboek
 instance. This includes the installation, updating, configuration, and backing
diff --git a/doc/administration/docker.rst b/doc/administration/docker.rst
new file mode 100644
index 0000000..68f474f
--- /dev/null
+++ b/doc/administration/docker.rst
@@ -0,0 +1,159 @@
+Container Setup
+===============
+
+Like most applications, Fietsboek can be installed in a Docker container. This
+allows you to have Fietsboek isolated from the rest of the system, e.g. if you
+need to run a newer Python version.
+
+.. note::
+
+    Fietsboek's ``Dockerfile`` has been tested with Podman_, but it should
+    work just as well with Docker_.
+
+    The commands in this article use ``docker`` for the sake of consistency,
+    but it will work the same if you replace ``docker`` with ``podman`` (or use
+    ``podman-docker``).
+
+.. _Podman: https://podman.io/
+.. _Docker: https://www.docker.com/
+
+Building the Image
+------------------
+
+You can build the image by running ``docker build`` in the main directory. Note
+that the build will use the currently checked out version of Fietsboek, so make
+sure you are on the right version that you want to use::
+
+    docker build -t fietsboek .
+
+Container Layout
+----------------
+
+The container reserves three volumes:
+
+* ``/fietsboek/database`` for the SQL database.
+* ``/fietsboek/data`` for the track data.
+* ``/fietsboek/pages`` for the custom pages.
+
+Per default, the configuration file is expected at
+``/fietsboek/fietsboek.ini``, and the `Gunicorn configuration`_ at
+``/fietsboek/gunicorn.conf.py``.
+
+.. _Gunicorn configuration: https://docs.gunicorn.org/en/latest/configure.html#configuration-file
+
+Configuration
+-------------
+
+There are two ways to configure the Fietsboek instance in the container. You
+can either mount a custom configuration file to ``/fietsboek/fietsboek.ini``,
+or you can change common settings via environment variables. Note that you need
+to choose one way, as mounting a custom configuration will disable the
+environment variable parsing.
+
+If you need to change a lot of settings, using a custom configuration file is
+the prefered way. It follows the same syntax and settings as described in
+:doc:`configuration`. Keep the container layout in mind when setting the data
+directory and database location (or make sure that they are on other volumes).
+
+An example command could look like this::
+
+    docker run -v ./production.ini:/fietsboek/fietsboek.ini fietsboek
+
+If you simply want to get a quick instance up and running, the method of
+overwriting single configuration values via environment variables is quicker.
+This way, you do not need to provide the full configuration file, but simply
+the options that diverge from the default values::
+
+    docker run -e REDIS_URL=redis://localhost fietsboek
+
+The following environment variables are supported:
+
+=============================== ===============================
+Environment variable            Setting
+=============================== ===============================
+``REDIS_URL`` [#f1]_            ``redis.url``
+``SQLALCHEMY_URL``              ``sqlalchemy.url``
+``DATA_DIR``                    ``fietsboek.data_dir``
+``SESSION_KEY`` [#f2]_          ``session_key``
+``ENABLE_ACCOUNT_REGISTRATION`` ``enable_account_registration``
+``DEFAULT_LOCALE_NAME``         ``pyramid.default_locale_name``
+``EMAIL_FROM``                  ``email.from``
+``EMAIL_SMTP_URL``              ``email.smtp_url``
+``EMAIL_USERNAME``              ``email.username``
+``EMAIL_PASSWORD``              ``email.password``
+=============================== ===============================
+
+.. [#f1] Required.
+.. [#f2] Defaults to a random string.
+
+The ``fietsboek.pages`` setting is not exposed, as you can simply mount the
+directory containing the pages to ``/fietsboek/pages``.
+
+Upgrading
+---------
+
+The image is configured to automatically run ``fietsupdate`` at the start.
+Therefore, simply updating the image to the new Fietsboek version should work
+and the container will automatically migrate the data:
+
+.. code-block:: bash
+
+    # ... assume we checked out the new code, build the new image:
+    docker build -t fietsboek .
+    # Run the new code, taking the data from the old version:
+    docker run --volumes-from=OLD_CONTAINER_ID -e ... fietsboek
+
+.. warning::
+
+    As always, back up your data before doing an update!
+
+Maintenance & Cronjobs
+----------------------
+
+The image contains the maintenance tools ``fietsctl`` and ``fietscron``. You
+can execute them in the container:
+
+.. code-block:: bash
+
+    # Get a user list ...
+    docker exec -ti CONTAINER_ID fietsctl userlist -c fietsboek.ini
+    # Run the cronjobs ...
+    docker exec -ti CONTAINER_ID fietscron -c fietsboek.ini
+    # ... and so on
+
+Docker Compose
+--------------
+
+Since Fietsboek needs other services (such as a Redis_ instance, and optionally
+a SQL server like PostgreSQL_ or MariaDB_), it makes sense to put those
+services together in a ``docker-compose.yml`` file.
+
+A minimal example is given here:
+
+.. code-block:: yaml
+
+    services:
+      redis:
+        image: redis
+
+      fietsboek:
+        image: fietsboek
+        ports:
+          - "8000:8000"
+        environment:
+          - REDIS_URL=redis://redis
+        volumes:
+          - fietsboek-data:/fietsboek/data
+          - fietsboek-database:/fietsboek/database
+
+    volumes:
+      fietsboek-data:
+      fietsboek-database:
+
+
+This example shows how to use the environment-based configuration mechanism to
+get a instance up quickly, without changing the defaults too much.
+
+.. _Redis: https://redis.com/
+.. _PostgreSQL: https://www.postgresql.org/
+.. _MariaDB: https://mariadb.org/