Merge pull request #677 from usrpro/feat-faq

Implement a FAQ

docs/faq.rst

@@ -0,0 +1,276 @@
+Frequently asked questions
+==========================
+
+Informational
+-------------
+
+Where to ask questions?
+```````````````````````
+
+First, please read this FAQ to check if your question is listed here.
+Simple questions best fit in our `Matrix`_ room.
+For more complex questions, you can always open a `new issue`_ on GitHub.
+We actively monitor the issues list.
+
+
+My installation is broken!
+``````````````````````````
+
+We're sorry to hear that. Please check for common mistakes and troubleshooting
+advice in the `Technical issues`_ section of this page.
+
+I think I found a bug!
+``````````````````````
+
+If you did not manage to solve the issue using this FAQ and there is not any 
+`open issues`_ describing the same problem, you can continue to open a
+`new issue`_ on GitHub.
+
+I want a new feature or enhancement!
+````````````````````````````````````
+
+Great! We are always open for suggestions. We currently maintain two tags:
+
+- `Enhancement issues`_: Typically used for optimization of features in the project.
+- `Feature request issues`_: For implementing new functionality,
+  plugins and applications.
+
+Please check if your idea (or something similar) is already mentioned there.
+If there is one open, you can choose to vote with a thumbs up, so we can
+estimate the popular demand. Please refrain from writing comments like
+*"me too"* as it clobbers the actual discussion.
+
+If you can't find anything similar, you can open a `new issue`_.
+Please also share (where applicable):
+
+- Use case: how does this improve the project?
+- Any research done on the subject. Perhaps some links to upstream website,
+  reference implementations etc.
+
+Why does my feature/bug take so long to solve?
+``````````````````````````````````````````````
+
+You should be aware that creating, maintaining and expanding a mail server
+distribution requires a lot of effort. Mail servers are highly exposed to hacking attempts,
+open relay scanners, spam and malware distributors etc. We need to work in a safe way and
+have to prevent pushing out something quickly.
+
+**TODO: Move the next section into the contributors part of docs**
+We currently maintain a strict work flow:
+
+#. Someone writes a solution and sends a pull request;
+#. We use Travis-CI for some very basic building and testing;
+#. The pull request needs to be code-reviewed and tested by at least two members
+   from the contributors team.
+  
+Please consider that this project is mostly developed in people their free time.
+We thank you for your understanding and patience.
+
+I would like to donate (for a feature)
+``````````````````````````````````````
+
+Donations are welcome at the `patreon`_ account of the project lead. It will be used to pay
+for infra structure and project related costs. If there are leftovers, it will be distributed
+among the developers.
+
+It is not yet possible to pay for a specific feature. We don't have
+any bounty system implemented. Feel free to come with suggestions in
+our ongoing `project management`_ discussion issue.
+
+
+.. _`Matrix`: https://matrix.to/#/#mailu:tedomum.net
+.. _`open issues`: https://github.com/Mailu/Mailu/issues
+.. _`new issue`: https://github.com/Mailu/Mailu/issues/new
+.. _`Enhancement issues`: https://github.com/Mailu/Mailu/issues?q=is%3Aissue+is%3Aopen+label%3Atype%2Fenhancement
+.. _`Feature request issues`: https://github.com/Mailu/Mailu/issues?q=is%3Aopen+is%3Aissue+label%3Atype%2Ffeature
+.. _`patreon`: https://patreon.com/kaiyou
+.. _`project management`: https://github.com/Mailu/Mailu/issues/508
+
+Deployment related
+------------------
+
+How does Mailu scale up?
+````````````````````````
+
+Recent works allow Mailu to be deployed in Docker Swarm and Kubernetes.
+This means it can be scaled horizontally. For more information, refer to :ref:`kubernetes`
+or the `Docker swarm howto`_.
+
+*Issue reference:* `165`_, `520`_.
+
+How to achieve HA / failover?
+`````````````````````````````
+
+The mailboxes and databases for Mailu are kept on the host filesystem under ``$ROOT/``.
+For making the **storage** highly available, all sorts of techniques can be used:
+
+- Local raid-1
+- btrfs in raid configuration
+- Distributed network filesystems such as GlusterFS or CEPH
+
+Note that no storage HA solution can protect against incidental deletes or file corruptions.
+Therefore it is advised to create backups on a regular base!
+
+A backup MX can be configured as **failover**. For this you need a separate server running
+Mailu. On that server, your domains will need to be setup as "Relayed domains", pointing
+to you main server. MX records for the mail domains with a higher priority number will have
+to point to this server. Please be aware that a backup MX can act as a `spam magnet`_.
+
+For **service** HA, please see: `How does Mailu scale up?`_
+
+
+*Issue reference:* `177`_, `591`_.
+
+.. _`spam magnet`: https://blog.zensoftware.co.uk/2012/07/02/why-we-tend-to-recommend-not-having-a-secondary-mx-these-days/
+
+
+Can I run Mailu without host iptables?
+``````````````````````````````````````
+
+When disabling iptables in docker, its forwarding proxy process takes over.
+This creates the situation that every incoming connection on port 25 seems to come from the
+local network (docker's 172.17.x.x) and is accepted. This causes an open relay!
+
+For that reason we do **not** support deployment on Docker hosts without iptables.
+
+*Issue reference:* `332`_.
+
+How can I override settings?
+````````````````````````````
+
+Postfix, dovecot and Rspamd support overriding configuration files. Override files belong in
+``$ROOT/overrides``. Please refer to the official documentation of those programs for the
+correct syntax. The following file names will be taken as override configuration:
+
+- `Postfix`_ - ``postfix.cf``;
+- `Dovecot`_ - ``dovecot.conf``;
+- `Rspamd`_ - All files in the ``rspamd`` sub-directory.
+
+.. _`Postfix`: http://www.postfix.org/postconf.5.html
+.. _`Dovecot`: https://wiki.dovecot.org/ConfigFile
+.. _`Rspamd`: https://www.rspamd.com/doc/configuration/index.html
+
+.. _`Docker swarm howto`: https://github.com/Mailu/Mailu/tree/master/docs/swarm/master
+.. _`165`: https://github.com/Mailu/Mailu/issues/165
+.. _`177`: https://github.com/Mailu/Mailu/issues/177
+.. _`332`: https://github.com/Mailu/Mailu/issues/332
+.. _`520`: https://github.com/Mailu/Mailu/issues/520
+.. _`591`: https://github.com/Mailu/Mailu/issues/591
+
+Technical issues
+----------------
+
+In this section we are trying to cover the most common problems our users are having.
+If your issue is not listed here, please consult issues with the `troubleshooting tag`_.
+
+Changes in .env don't propagate
+```````````````````````````````
+
+Variables are sent to the containers at creation time. This means you need to take the project
+down and up again. A container restart is not sufficient.
+
+.. code-block:: bash
+
+  docker-compose down && \
+  docker-compose up -d
+
+*Issue reference:* `615`_.
+
+TLS certificate issues
+``````````````````````
+
+When there are issues with the TLS/SSL certificates, Mailu denies service on secure ports.
+This is a security precaution. Symptoms are:
+
+- 403 browser errors;
+
+These issues are typically caused by four scenarios:
+
+#. ``TLS_FLAVOR=notls`` in ``.env``;
+#. Certificates expired;
+#. When ``TLS_FLAVOR=letsencrypt``, it might be that the *certbot* script is not capable of
+   obtaining the certificates for your domain. See `letsencrypt issues`_
+#. When ``TLS_FLAVOR=certs``, certificates are supposed to be copied to ``/mailu/certs``.
+   Using an external ``letsencrypt`` program, it tends to happen people copy the whole
+   ``letsencrypt/live`` directory containing symlinks. Symlinks do not resolve inside the
+   container and therefore it breaks the TLS implementation.
+
+letsencrypt issues
+..................
+
+In order to determine the exact problem on TLS / Let's encrypt issues, it might be helpful
+to check the logs.
+
+.. code-block:: bash
+
+  docker-compose logs front | less -R
+  docker-compose exec front less /var/log/letsencrypt/letsencrypt.log
+
+Common problems:
+
+- Port 80 not reachable from outside.
+- Faulty DNS records: make sure that all ``HOSTNAMES`` have **A** (IPv4) and **AAAA** (IPv6)
+  records, pointing the the ``BIND_ADDRESS4`` and ``BIND_ADDRESS6``.
+- DNS cache not yet expired. It might be that old / faulty DNS records are stuck in a cache
+  en-route to letsencrypt's server. The time this takes is set by the ``TTL`` field in the
+  records. You'll have to wait at least this time after changing the DNS entries.
+  Don't keep trying, as you might hit `rate-limits`_.
+
+.. _`rate-limits`: https://letsencrypt.org/docs/rate-limits/
+
+Copying certificates
+....................
+
+As mentioned above, care must be taken not to copy symlinks to the ``/mailu/certs`` location.
+
+**The wrong way!:**
+
+.. code-block:: bash
+
+  cp -r /etc/letsencrypt/live/domain.com /mailu/certs
+
+**The right way!:**
+
+.. code-block:: bash
+
+  mkdir -p /mailu/certs
+  cp /etc/letsencrypt/live/domain.com/privkey.pem /mailu/certs/key.pem
+  cp /etc/letsencrypt/live/domain.com/fullchain.pem /mailu/certs/cert.pem
+
+See also :ref:`external_certs`.
+
+*Issue reference:* `426`_, `615`_.
+
+Do you support Fail2Ban?
+````````````````````````
+Fail2Ban is not included in Mailu. Fail2Ban needs to modify the host's IP tables in order to
+ban the addresses. We consider such a program should be run on the host system and not
+inside a container. The ``front`` container does use authentication rate limiting to slow
+down brute force attacks.
+
+We *do* provide a possibility to export the logs from the ``front`` service to the host.
+For this you need to set ``LOG_DRIVER=journald`` or ``syslog``, depending on the log
+manager of the host. You will need to setup the proper Regex in the Fail2Ban configuration.
+Be aware that webmail authentication appears to come from the Docker network,
+so don't ban those addresses!
+
+*Issue reference:* `85`_, `116`_, `171`_, `584`_, `592`_.
+
+Users can't change their password from webmail
+``````````````````````````````````````````````
+
+All users have the abilty to login to the admin interface. Non-admin users
+have only restricted funtionality such as changing their password and the
+spam filter weight settings.
+
+*Issue reference:* `503`_.
+
+.. _`troubleshooting tag`: https://github.com/Mailu/Mailu/issues?utf8=%E2%9C%93&q=label%3Afaq%2Ftroubleshooting
+.. _`85`: https://github.com/Mailu/Mailu/issues/85
+.. _`116`: https://github.com/Mailu/Mailu/issues/116
+.. _`171`: https://github.com/Mailu/Mailu/issues/171
+.. _`426`: https://github.com/Mailu/Mailu/issues/426
+.. _`503`: https://github.com/Mailu/Mailu/issues/503
+.. _`584`: https://github.com/Mailu/Mailu/issues/584
+.. _`592`: https://github.com/Mailu/Mailu/issues/592
+.. _`615`: https://github.com/Mailu/Mailu/issues/615

docs/index.rst

@@ -44,6 +44,7 @@ the version of Mailu that you are running.
 
    general
    features
+   faq
    releases
    demo
 

docs/kubernetes/mailu/index.rst

@@ -1,5 +1,7 @@
-Install Mailu master on kubernetes
+.. _kubernetes:
-==================================
+
+Kubernetes setup
+================
 
 Prequisites
 -----------

docs/maintain.rst

@@ -28,6 +28,33 @@ Logs are managed by Docker directly. You can easily read your logs using:
 
 Docker is able to forward logs to multiple log engines. Read the following documentation for details: https://docs.docker.com/engine/admin/logging/overview/.
 
+.. _external_certs:
+
+Managing of external Let's encrypt certificates
+-----------------------------------------------
+
+When you are not using the embedded ``letsencrypt`` option from Mailu,
+you cannot make use of it's symlink functionality in the ``letsencrypt/live`` directory.
+You should take care that after every renewal new certificates are copied to ``/mailu/certs`` and
+the *nginx* process in the ``front`` container is reloaded.
+
+In the case of *certbot* you could write a script to be executed as `deploy hook`_.  Example:
+
+.. code-block:: bash
+
+  #!/bin/sh
+  cp /etc/letsencrypt/live/domain.com/privkey.pem /mailu/certs/key.pem || exit 1
+  cp /etc/letsencrypt/live/domain.com/fullchain.pem /mailu/certs/cert.pem || exit 1
+  docker exec mailu_front_1 nginx -s reload
+
+And the certbot command you will use in crontab would look something like:
+
+.. code-block:: bash
+
+  52 0,12 * * * root /usr/bin/certbot renew --deploy-hook /path/to/script.sh
+
+.. _`deploy hook`: https://certbot.eff.org/docs/using.html#renewing-certificates
+
 Migrating an instance
 ---------------------