diff --git a/docs/faq.rst b/docs/faq.rst index 8c5b5598..81d51b86 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -55,6 +55,7 @@ distribution requires a lot of effort. Mail servers are highly exposed to hackin 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; @@ -65,8 +66,8 @@ We currently maintain a strict work flow: Please consider that this project is mostly developed in people their free time. We thank you for your understanding and patience. -I would to donate (for a feature) -````````````````````````````````` +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 @@ -88,10 +89,90 @@ our ongoing `project management`_ discussion issue. Deployment related ------------------ - Technical issues ---------------- +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`_. + + WIP: Link to `troubleshooting`_ related issues will be in the bottom of this section. +.. _`426`: https://github.com/Mailu/Mailu/issues/426 +.. _`615`: https://github.com/Mailu/Mailu/issues/615 .. _`troubleshooting`: https://github.com/Mailu/Mailu/issues?utf8=%E2%9C%93&q=label%3Afaq%2Ftroubleshooting