Documentation how to use Postgresql

docs/database.rst

@@ -0,0 +1,77 @@
+Changing the database back-end
+==============================
+
+By default Mailu uses a SQLite database. Recently, we have changed the internals of Mailu
+to enable the support of alternative database solutions. At this moment we have only included 
+the possibility to use a Postgresql database. This functionality should still be considered
+experimental!
+
+Mailu Postgresql
+----------------
+
+Mailu optionally comes with a pre-configured Postgresql image.
+This images has the following features:
+
+- Automatic creation of users, db, extensions and password;
+- TCP connections are only allowed from the mailu `SUBNET`;
+- Automatic minutely *wal archiving* and weekly `pg_basebackup`;
+- Automatic cleaning of *wal archives* and *base backups*;
+  Two versions always remain available;
+- When `/data` is empty and backups are present, the backups are restored automatically;
+  Useful in swarm environments, since the /data directory should not be on any network 
+  filesystem (performance).
+
+To make use of this functionality, just select *Postgresql* as database flavor.
+Don't select the usage of an external database. The ``docker-compose.yml`` and ``mailu.env``
+will pull in ``mailu/postgresql``. This image and ``mailu/admin`` contain all the scripts
+to automatically setup the database.
+
+After bring up the service, it might be useful to check the logs with:
+
+.. code-block:: bash
+
+  docker-compose logs -f admin database
+
+External Postgresql
+-------------------
+
+It is also possible to use a Postgresql database server, hosted elsewhere.
+In this case you'll have to take to create an empty database for Mailu, corresponding user,
+password and sufficient privileges on the database to ``CREATE TABLE``, ``DROP`` etc.
+Usually making the user owner of the database would be the easiest thing to do.
+Don't forget to set ``pg_hba.conf`` accordingly.
+
+The database will also need the Citext extension installed.
+This is usually included in a package called "postgresql-contrib".
+The exact name may vary between distributions.
+
+The following commands can serve as an example on how to set up postgresql for Mailu usage.
+Adjust this to your own liking.
+
+.. code-block:: bash
+
+  $ sudo su - postgres
+  $ psql
+  psql (10.6)
+  Type "help" for help.
+
+  postgres=# create user mailu;
+  CREATE ROLE
+  postgres=# alter user mailu password 'my_secure_pass';
+  ALTER ROLE
+  postgres=# create database mailu owner mailu;
+  CREATE DATABASE
+  postgres=# \c mailu
+  You are now connected to database "mailu" as user "postgres".
+  mailu=# create extension citext;
+  CREATE EXTENSION
+  mailu=# \q
+
+In ``pg_hba.conf`` there should be a line like this:
+
+.. code-block:: bash
+
+  host    mailu           mailu           <mailu_host>/32            md5
+
+Note that this example is the bare-minimum to get Mailu working. It goes without saying that
+the database admin will have to setup his own means of backups and TLS encrypted connections.

optional/postgresql/conf/pg_hba.conf

@@ -79,7 +79,7 @@
 # "local" is for Unix domain socket connections only
 local   all             all                                     peer map=local
 # IPv4 connections:
-host    all             mailu           {{ SUBNET }}            md5
+host    mailu           mailu           {{ SUBNET }}            md5
 host    postgres        health          127.0.0.1/32            trust
 # IPv6 local connections:
 host    all             all             ::1/128                 reject