Documentation on IPv6

CHANGELOG.md

@@ -80,6 +80,7 @@ v1.6.0 - unreleased
 - Enhancement: Include favicon package ([#801](https://github.com/Mailu/Mailu/issues/801), ([#802](https://github.com/Mailu/Mailu/issues/802))
 - Enhancement: Add logging at critical places in python start.py scripts. Implement LOG_LEVEL to control verbosity ([#588](https://github.com/Mailu/Mailu/issues/588))
 - Enhancement: Mark message as seen when reporting as spam
+- Enhancement: Better support and document IPv6 ([#827](https://github.com/Mailu/Mailu/issues/827))
 - Upstream: Update Roundcube
 - Upstream: Update Rainloop
 - Bug: Rainloop fails with "domain not allowed" ([#93](https://github.com/Mailu/Mailu/issues/93))

docs/faq.rst

@@ -134,6 +134,49 @@ You're mail service will be reachable for IMAP, POP3, SMTP and Webmail at the ad
 
 *Issue reference:* `742`_, `747`_.
 
+How to make IPv6 work?
+``````````````````````
+
+Docker currently does not expose the IPv6 ports properly, as it does not interface with ``ip6tables``.
+Lets start with quoting everything that's wrong:
+
+  Unfortunately, initially Docker was not created with IPv6 in mind.
+  It was added later and, while it has come a long way, is still not as usable as one would want.
+  Much discussion is still going on as to how IPv6 should be used in a containerized world;
+  See the various GitHub issues linked below:
+  
+  - Giving each container a publicly routable address means all ports (even unexposed / unpublished ports) are suddenly
+    reachable by everyone, if no additional filtering is done
+    (`docker/docker#21614 <https://github.com/docker/docker/issues/21614>`_)
+  - By default, each container gets a random IPv6, making it impossible to do properly do DNS;
+    the alternative is to assign a specific IPv6 address to each container,
+    still an administrative hassle (`docker/docker#13481 <https://github.com/docker/docker/issues/13481>`_)
+  - Published ports won't work on IPv6, unless you have the userland proxy enabled
+    (which, for now, is enabled by default in Docker)
+  - The userland proxy, however, seems to be on its way out
+    (`docker/docker#14856 <https://github.com/docker/docker/issues/14856>`_) and has various issues, like:
+  
+    - It can use a lot of RAM (`docker/docker#11185 <https://github.com/docker/docker/issues/11185>`_)
+    - Source IP addresses are rewritten, making it completely unusable for many purposes, e.g. mail servers 
+      (`docker/docker#17666 <https://github.com/docker/docker/issues/17666>`_),
+      (`docker/libnetwork#1099 <https://github.com/docker/libnetwork/issues/1099>`_).
+  
+  -- `Robbert Klarenbeek <https://github.com/robbertkl>`_ (docker-ipv6nat author)
+
+So, how to make it work? Well, by using `docker-ipv6nat`_! This nifty container will set up ``ip6tables``,
+just as Docker would do for IPv4. We know that nat-ing is not advised in IPv6,
+however exposing all containers to public network neither. The choice is ultimately yous.
+
+Mailu `setup utility`_ generates a safe IPv6 ULA subnet by default. So when you run the following command,
+Mailu will start to function on IPv6:
+
+.. code-block:: bash
+
+  docker run -d --restart=always -v /var/run/docker.sock:/var/run/docker.sock:ro --privileged --net=host robbertkl/ipv6nat
+
+.. _`docker-ipv6nat`: https://github.com/robbertkl/docker-ipv6nat
+.. _`setup utility`: https://setup.mailu.io
+
 How does Mailu scale up?
 ````````````````````````
 

setup/templates/steps/compose/03_expose.html

@@ -31,8 +31,7 @@ avoid generic all-interfaces addresses like <code>0.0.0.0</code> or <code>::</co
 </div>
 
 <div class="form-group" id="ipv6" style="display: none">
-  <p><span class="label label-warning">Warning</span> You must use specific addresses, please
+  <p><span class="label label-danger">Read this:</span> Docker currently does not expose the IPv6 ports properly, as it does not interface with <code>ip6tables</code>. Be sure to read our <a href="https://mailu.io/{{ version }}/faq.html#how-to-make-ipv6-work">FAQ section</a>!</p>
-	avoid generic all-interfaces addresses like <code>0.0.0.0</code> or <code>::</code>.</p>
   <label>IPv6 listen address</label>
 <!--   Validates IPv6 address -->
   <input class="form-control" type="text" name="bind6" value="::1"