Merge pull request #840 from usrpro/setup-docs

Setup docs

docs/compose/.env

@@ -1,3 +1,5 @@
+# WARNING: this file is being deprecated over the new setup utility, found at https://setup.mailu.io
+
 # Mailu main configuration file
 ## Most configuration variables can be modified through the Web interface,
 # these few settings must however be configured before starting the mail

docs/compose/docker-compose.yml

@@ -1,3 +1,5 @@
+# WARNING: this file is being deprecated over the new setup utility, found at https://setup.mailu.io
+
 version: '2'
 
 services:

docs/compose/setup.rst

@@ -12,34 +12,22 @@ Mailu will store all of its persistent data in a path of your choice
   mkdir /mailu
   cd /mailu
 
-Download the initial configuration file
----------------------------------------
+Create the configuration files
+------------------------------
 
-Docker Compose configuration is stored in a file named
-:download:`docker-compose.yml`. Additionally, Mailu
-relies on a :download:`.env` file for various settings. Download
-the proper template files from the git repository. To download the configuration
-for the ``VERSION_TAG`` branch, use:
+Docker Compose configuration is stored in a file named ``docker-compose.yml``.
+Additionally, Mailu relies on a ``mailu.env`` file for various settings.
+Both files can be generated by the `mailu setup utility`_. The setup utility
+is mostly self-explanatory, with some more additional information in this section.
 
-.. code-block:: bash
+.. _`mailu setup utility`: https://setup.mailu.io
 
-  wget https://mailu.io/VERSION_TAG/_downloads/docker-compose.yml
-  wget https://mailu.io/VERSION_TAG/_downloads/.env
-
-Important configuration variables
----------------------------------
-
-Open the ``.env`` file and review the following variable settings:
-
-- Change ``ROOT`` if you have your setup directory in a different location then ``/mailu``.
-- Check ``VERSION`` to reflect the version you picked. (``master`` or ``1.5``).
-
-Make sure to read the comments in the file and instructions from the :ref:`common_cfg` section.
+.. _tls_flavor:
 
 TLS certificates
 ````````````````
 
-Set the ``TLS_FLAVOR`` to one of the following
+Sets the ``TLS_FLAVOR`` to one of the following
 values:
 
 - ``cert`` is the default and requires certificates to be setup manually;
@@ -59,7 +47,7 @@ values:
 Bind address
 ````````````
 
-Modify ``BIND_ADDRESS4`` and ``BIND_ADDRESS6`` to match the public IP addresses assigned to your server. For IPv6 you will need the ``<global>`` scope address. 
+The bind addresses need to match the public IP addresses assigned to your server. For IPv6 you will need the ``<global>`` scope address.
 
 You can find those addresses by running the following:
 
@@ -81,56 +69,17 @@ you would simply like the server to listen on all interfaces, use ``0.0.0.0`` an
 
 .. _issues: https://github.com/Mailu/Mailu/issues/641
 
-Enable optional features
-------------------------
+Review configuration variables
+------------------------------
 
-Some of Mailu features are not used by every user and are thus not enabled in a
-default configuration.
-
-A Webmail is a Web interface exposing an email client. Mailu webmails are
-bound to the internal IMAP and SMTP server for users to access their mailbox through
-the Web. By exposing a complex application such as a Webmail, you should be aware of
-the security implications caused by such an increase of attack surface. The ``WEBMAIL``
-configuration option must be one of the following:
-
-- ``none`` is the default value, no Webmail service will be exposed;
-- ``roundcube`` will run the popular Roundcube Webmail;
-- ``rainloop`` will run the popular Rainloop Webmail.
-
-The administration interface is not exposed on the public address by default,
-you will need to set the ``ADMIN`` variable accordingly:
-
-- ``true`` will expose the admin interface in ``/admin``;
-- ``false`` (or any other value) will disable this behaviour.
-
-A Webdav server exposes a Dav interface over HTTP so that clients can store
-contacts or calendars using the mail account. This can be enabled using the `WEBDAV`
-setting. The configuration option must be one of the following:
-
-- ``none`` is the default value, no webdav service will be exposed;
-- ``radicale`` exposes the radicale Webdav service.
-
-An antivirus server helps fighting large scale virus spreading campaigns
-that leverage e-mail for initial infection. This can be setup using the ``ANTIVIRUS``
-setting. The configuration option must be one of the following:
-
-- ``none`` disables antivirus checks;
-- ``clamav`` is the default values, the popular ClamAV antivirus is enabled.
-
-Make sure that you have at least 1GB of memory for ClamAV to load its signature
-database.
-
-If you run Mailu behind a reverse proxy you can use ``REAL_IP_HEADER`` and
-``REAL_IP_FROM`` to set the values of respective the Nginx directives
-``real_ip_header`` and ``set_real_ip_from``. The ``REAL_IP_FROM`` configuration
-option is a comma-separated list of IPs (or CIDRs) of which for each a
-``set_real_ip_from`` directive is added in the Nginx configuration file.
+After downloading the files, open ``mailu.env`` and review the variable settings.
+Make sure to read the comments in the file and instructions from the :ref:`common_cfg` page.
 
 Finish setting up TLS
 ---------------------
 
 Mailu relies heavily on TLS and must have a key pair and a certificate
-available, at least for the hostname configured in the ``.env`` file.
+available, at least for the hostname configured in the ``mailu.env`` file.
 
 If you set ``TLS_FLAVOR`` to ``cert`` or ``mail`` then you must create a ``certs`` directory
 in your root path and setup a key-certificate pair there:
@@ -155,4 +104,4 @@ Finally, you must create the initial admin user account:
 
 This will create a user named ``me@example.net`` with password ``password`` and administration privileges. Connect to the Web admin interface and change the password to a strong one.
 
-  .. note:: It is vitally important that either a user with the same email as ``POSTMASTER`` in your ``.env`` exists, or you remember to create an alias with this name after you log in. All kinds of strange errors will occur as a result of not doing so!
+  .. note:: It is vitally important that either a user with the same email as ``POSTMASTER`` in your ``mailu.env`` exists, or you remember to create an alias with this name after you log in. All kinds of strange errors will occur as a result of not doing so!

docs/configuration.rst

@@ -1,5 +1,9 @@
-Mailu configuration settings
-============================
+Configuration reference
+=======================
+
+This page explains the variables found in ``mailu.env``.
+In most cases ``mailu.env`` is setup correctly by the setup utility and can be left as-is.
+However, some advanced settings or modifications can be done by modifying this file.
 
 .. _common_cfg:
 
@@ -37,6 +41,9 @@ The ``AUTH_RATELIMIT`` holds a security setting for fighting attackers that
 try to guess user passwords. The value is the limit of requests that a single
 IP address can perform against IMAP, POP and SMTP authentication endpoints.
 
+The ``TLS_FLAVOR`` sets how Mailu handles TLS connections. Setting this value to
+``notls`` will cause Mailu not to server any web content! More on :ref:`tls_flavor`.
+
 Mail settings
 -------------
 

docs/docker-compose.yml

@@ -1,28 +1,10 @@
+# This file is used to test the mailu/docs website
+# Deployment files can be found on github.com/mailu/infra
+
 version: '3'
 
-
 services:
-  docs_master:
-    image: mailu/docs:master
-    networks:
-      - web
-    labels:
-      - traefik.enable=true
-      - traefik.port=80
-      - traefik.main.frontend.rule=Host:${ADDRESS};PathPrefix:/master/
-
-  docs_15:
-    image: mailu/docs:1.5
-    networks:
-      - web
-    labels:
-      - traefik.enable=true
-      - traefik.port=80
-      - traefik.root.frontend.redirect.regex=.*
-      - traefik.root.frontend.redirect.replacement=/1.5/
-      - traefik.root.frontend.rule=Host:${ADDRESS};PathPrefix:/
-      - traefik.main.frontend.rule=Host:${ADDRESS};PathPrefix:/1.5/
-
-networks:
-  web:
-    external: true
+  docs:
+    image: ${DOCKER_ORG:-mailu}/docs:${MAILU_VERSION:-master}
+    ports:
+      - 127.0.0.1:8000:80

docs/index.rst

@@ -53,10 +53,10 @@ the version of Mailu that you are running.
     :caption: Setup
 
     setup
-    configuration
     compose/requirements
     compose/setup
     kubernetes/mailu/index
+    configuration
     dns
     reverse
     database

setup/docker-compose.yml

@@ -1,50 +1,16 @@
-# This file is used to run the mailu/setup utility
+# This file is used to test the mailu/setup utility
+# Deployment files can be found on github.com/mailu/infra
 
 version: '3.6'
 
 services:
   redis:
     image: redis:alpine
-    networks:
-      - default
 
-  setup_master:
-    image: mailu/setup:master
-    networks:
-      - web
-      - default
+  setup:
+    image: ${DOCKER_ORG:-mailu}/setup:${MAILU_VERSION:-master}
     env_file: .env
-    environment:
-      this_version: "master"
-    labels:
-      - traefik.enable=true
-      - traefik.port=80
-      - traefik.docker.network=web
-      - traefik.main.frontend.rule=Host:${ADDRESS};PathPrefix:/master/
     depends_on:
       - redis
-
-  setup_release:
-    image: mailu/setup:${RELEASE}
-    networks:
-      - web
-      - default
-    env_file: .env
-    environment:
-      this_version: ${RELEASE}
-    labels:
-      - traefik.enable=true
-      - traefik.port=80
-      - traefik.docker.network=web
-      - traefik.root.frontend.redirect.regex=.*
-      - traefik.root.frontend.redirect.replacement=/${RELEASE}/
-      - traefik.root.frontend.rule=Host:${ADDRESS};PathPrefix:/
-      - traefik.main.frontend.rule=Host:${ADDRESS};PathPrefix:/${RELEASE}/
-    depends_on:
-      - redis
-
-networks:
-  web:
-    external: true
-  default:
-    external: false
+    ports:
+      - 127.0.0.1:8001:80

setup/server.py

@@ -11,7 +11,7 @@ import ipaddress
 import hashlib
 
 
-version = os.getenv("this_version")
+version = os.getenv("this_version", "master")
 static_url_path = "/" + version + "/static"
 app = flask.Flask(__name__, static_url_path=static_url_path)
 flask_bootstrap.Bootstrap(app)

setup/templates/steps/compose/02_services.html

@@ -1,13 +1,13 @@
 {% call macros.panel("info", "Step 3 - pick some features") %}
 <p>Mailu comes with multiple base features, including a specific admin
-interface, Web email clients (webmails), antispam, antivirus, etc. If you
-wish to disable some of these features, you are free to do so.</p>
-
-<p>Emails will be available through IMAP and POP3. You may also enable a Web
-email client. These do add some complexity but provide an easier way of
-accessing messages for beginner users.</p>
+interface, Web email clients, antispam, antivirus, etc.
+In this section you can enable the services to you liking.</p>
 
 <!-- 	Switched from radio buttons to dropdown menu in order to remove the checkbox -->
+<p>A Webmail is a Web interface exposing an email client. Mailu webmails are
+bound to the internal IMAP and SMTP server for users to access their mailbox through
+the Web. By exposing a complex application such as a Webmail, you should be aware of
+the security implications caused by such an increase of attack surface.<p>
 <div class="form-group">
   <label>Enable Web email client (and path to the Web email client)</label>
 <!--   <div class="radio"> -->
@@ -26,10 +26,9 @@ accessing messages for beginner users.</p>
   </div>
 </div>
 
-<p>Email filtering is a really important features. You can still disable it, which
-will prevent Mailu from doing spam filtering, virus filtering, and from applying
-white and blacklists that you may configure in the admin interface. You may
-also disable the antivirus if required (it does use aroung 1GB of ram).</p>
+<p>An antivirus server helps fighting large scale virus spreading campaigns that leverage
+e-mail for initial infection. Make sure that you have at least 1GB of memory for ClamAV to
+load its signature database.</p>
 
 <div class="form-check form-check-inline">
   <label class="form-check-label">
@@ -38,6 +37,9 @@ also disable the antivirus if required (it does use aroung 1GB of ram).</p>
   </label>
 </div>
 
+<p>A Webdav server exposes a Dav interface over HTTP so that clients can store
+contacts or calendars using the mail account.</p>
+
 <div class="form-check form-check-inline">
   <label class="form-check-label">
     <input class="form-check-input" type="checkbox" name="webdav_enabled" value="radicale">
@@ -45,6 +47,8 @@ also disable the antivirus if required (it does use aroung 1GB of ram).</p>
   </label>
 </div>
 
+<p>Fetchmail allows to download mails over IMAP/POP3 and uploads it your Mailu mailbox.</p>
+
 <div class="form-check form-check-inline">
   <label class="form-check-label">
     <input class="form-check-input" type="checkbox" name="fetchmail_enabled" value="true">

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

@@ -10,7 +10,8 @@ IP addresses in order to expose its public services. You must at least setup
 an IPv4 or an IPv6 address if you wish to access Mailu.</p>
 
 <p><span class="label label-warning">Warning</span> You must use specific addresses, please
-avoid generic all-interfaces addresses like <code>0.0.0.0</code> or <code>::</code>.</p>
+avoid generic all-interfaces addresses like <code>0.0.0.0</code> or <code>::</code>.
+<a href="https://mailu.io/{{ version }}/compose/setup.html#bind-address">How to find these addresses.</a></p>
 
 <div class="form-group">
   <label>IPv4 listen address</label>
@@ -26,13 +27,14 @@ avoid generic all-interfaces addresses like <code>0.0.0.0</code> or <code>::</co
   		pattern="^s*((([0-9A-Fa-f]{1,4}:){7}([0-9A-Fa-f]{1,4}|:))|(([0-9A-Fa-f]{1,4}:){6}(:[0-9A-Fa-f]{1,4}|((25[0-5]|2[0-4]d|1dd|[1-9]?d)(.(25[0-5]|2[0-4]d|1dd|[1-9]?d)){3})|:))|(([0-9A-Fa-f]{1,4}:){5}(((:[0-9A-Fa-f]{1,4}){1,2})|:((25[0-5]|2[0-4]d|1dd|[1-9]?d)(.(25[0-5]|2[0-4]d|1dd|[1-9]?d)){3})|:))|(([0-9A-Fa-f]{1,4}:){4}(((:[0-9A-Fa-f]{1,4}){1,3})|((:[0-9A-Fa-f]{1,4})?:((25[0-5]|2[0-4]d|1dd|[1-9]?d)(.(25[0-5]|2[0-4]d|1dd|[1-9]?d)){3}))|:))|(([0-9A-Fa-f]{1,4}:){3}(((:[0-9A-Fa-f]{1,4}){1,4})|((:[0-9A-Fa-f]{1,4}){0,2}:((25[0-5]|2[0-4]d|1dd|[1-9]?d)(.(25[0-5]|2[0-4]d|1dd|[1-9]?d)){3}))|:))|(([0-9A-Fa-f]{1,4}:){2}(((:[0-9A-Fa-f]{1,4}){1,5})|((:[0-9A-Fa-f]{1,4}){0,3}:((25[0-5]|2[0-4]d|1dd|[1-9]?d)(.(25[0-5]|2[0-4]d|1dd|[1-9]?d)){3}))|:))|(([0-9A-Fa-f]{1,4}:){1}(((:[0-9A-Fa-f]{1,4}){1,6})|((:[0-9A-Fa-f]{1,4}){0,4}:((25[0-5]|2[0-4]d|1dd|[1-9]?d)(.(25[0-5]|2[0-4]d|1dd|[1-9]?d)){3}))|:))|(:(((:[0-9A-Fa-f]{1,4}){1,7})|((:[0-9A-Fa-f]{1,4}){0,5}:((25[0-5]|2[0-4]d|1dd|[1-9]?d)(.(25[0-5]|2[0-4]d|1dd|[1-9]?d)){3}))|:)))(%.+)?s*(\/([0-9]|[1-9][0-9]|1[0-1][0-9]|12[0-8]))?$">
 </div>
 
+<p>The unbound resolver enables Mailu to do DNSsec verification, DNS root lookups and caching. This also helps the antispam service not to get blocked by the public or ISP DNS servers.</p>
 <div class="form-check form-check-inline">
   <label class="form-check-label">
     <input class="form-check-input" type="checkbox" name="resolver_enabled" value="true">
     Enable unbound resolver
   </label>
 </div>
-
+<br><br>
 <div class="form-group">
   <label>Subnet of the docker network. This should not conflict with any networks to which your system is connected. (Internal and external!)</label>
   <input class="form-control" type="text" name="subnet" required pattern="^([0-9]{1,3}\.){3}[0-9]{1,3}(\/([0-9]|[1-2][0-9]|3[0-2]))$"

setup/templates/steps/config.html

@@ -1,8 +1,17 @@
+{% if flavor == "stack" %}
+{% call macros.panel("danger", "Docker stack / swarm is experimental") %}
+Setup is capable of generating a somewhat decent docker-compose.yml,
+for the docker stack flavor. However its usage is for advanced users an is experimental.
+Expect many challenges is shared mail storage and fail-over scenarios! Some user experiences
+have been <a href="https://github.com/Mailu/Mailu/blob/master/docs/swarm/master/README.md">shared on GitHub.</a>
+{% endcall %}
+{% endif %}
+
 {% call macros.panel("info", "Step 2 - Initial configuration") %}
 <p>Before starting some variables must be set</p>
 
 <div class="form-group">
-  <label>Root path: </label>
+  <label>Mailu storage path: </label>
 <!--   Validates path -->
   <input class="form-control" type="text" name="root" value="/mailu" required pattern="^/[-_A-Za-z0-9]+(/[-_A-Za-z0-9]*)*">
 </div>
@@ -27,7 +36,7 @@ Or in plain english: if receivers start to classify your mail as spam, this post
 </div>
 
 <div class="form-group">
-  <label>Choose how you wish to handle security (TLS) certificates</label>
+  <label>Choose how you wish to handle security <a href="https://mailu.io/{{ version }}/compose/setup.html#tls-certificates">TLS certificates</a></label>
   <br/>
   <select class="btn btn-primary dropdown-toggle" name="tls_flavor">
   	{% for tlsflavor in ["letsencrypt", "cert", "notls", "mail", "mail-letsencrypt"] %}
@@ -61,7 +70,7 @@ Or in plain english: if receivers start to classify your mail as spam, this post
   <label>Linked Website URL</label>
 <!--   Validates url with or without https:// -->
   <input class="form-control" type="url" name="website" value="https://mailu.io" required
-  		pattern="^(https?://)?([a-zA-Z0-9]([a-zA-ZäöüÄÖÜ0-9\-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]{2,6}$">
+		pattern="^(https?://)?([a-zA-Z0-9]([a-zA-ZäöüÄÖÜ0-9\-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]{2,}$">
 </div>
 
 <p>The admin interface is the main Mailu-specific bit, it provides tools to

setup/templates/steps/flavor.html

@@ -9,8 +9,5 @@ maintained by specific contributors.</p>
 <div class="radio">
   {{ macros.radio("flavor", "compose", "Compose", "simply using Docker Compose manager", flavor) }}
   {{ macros.radio("flavor", "stack", "Stack", "using stack deployments in a Swarm cluster", flavor) }}
-  {{ macros.radio("flavor", "rancher", "Rancher", "on top of the Rancher container manager", flavor) }}
-  {{ macros.radio("flavor", "kubernetes", "Kubernetes", "on top of the Kubernetes container manager", flavor) }}
 </div>
-
 {% endcall %}

setup/templates/steps/stack/02_services.html

@@ -1,19 +1,15 @@
 {% call macros.panel("info", "Step 3 - pick some features") %}
 <p>Mailu comes with multiple base features, including a specific admin
-interface, Web email clients (webmails), antispam, antivirus, etc. If you
-wish to disable some of these features, you are free to do so.</p>
-
-<p>Emails will be available through IMAP and POP3. You may also enable a Web
-email client. These do add some complexity but provide an easier way of
-accessing messages for beginner users.</p>
+interface, Web email clients, antispam, antivirus, etc.
+In this section you can enable the services to you liking.</p>
 
 <!-- 	Switched from radio buttons to dropdown menu in order to remove the checkbox -->
+<p>A Webmail is a Web interface exposing an email client. Mailu webmails are
+bound to the internal IMAP and SMTP server for users to access their mailbox through
+the Web. By exposing a complex application such as a Webmail, you should be aware of
+the security implications caused by such an increase of attack surface.<p>
 <div class="form-group">
   <label>Enable Web email client (and path to the Web email client)</label>
-<!--   <div class="radio"> -->
-<!--     {{ macros.radio("webmail_type", "roundcube", "RoundCube", "popular Webmail running on top of PHP") }} -->
-<!--     {{ macros.radio("webmail_type", "rainloop", "Rainloop", "lightweight Webmail based on PHP, no database") }} -->
-<!--   </div> -->
   <br/>
   <select class="btn btn-primary dropdown-toggle" name="webmail_type" id="webmail">
   	{% for webmailtype in ["none", "roundcube", "rainloop"] %}
@@ -26,10 +22,9 @@ accessing messages for beginner users.</p>
   </div>
 </div>
 
-<p>Email filtering is a really important features. You can still disable it, which
-will prevent Mailu from doing spam filtering, virus filtering, and from applying
-white and blacklists that you may configure in the admin interface. You may
-also disable the antivirus if required (it does use aroung 1GB of ram).</p>
+<p>An antivirus server helps fighting large scale virus spreading campaigns that leverage
+e-mail for initial infection. Make sure that you have at least 1GB of memory for ClamAV to
+load its signature database.</p>
 
 <div class="form-check form-check-inline">
   <label class="form-check-label">
@@ -38,6 +33,9 @@ also disable the antivirus if required (it does use aroung 1GB of ram).</p>
   </label>
 </div>
 
+<p>A Webdav server exposes a Dav interface over HTTP so that clients can store
+contacts or calendars using the mail account.</p>
+
 <div class="form-check form-check-inline">
   <label class="form-check-label">
     <input class="form-check-input" type="checkbox" name="webdav_enabled" value="radicale">
@@ -45,6 +43,8 @@ also disable the antivirus if required (it does use aroung 1GB of ram).</p>
   </label>
 </div>
 
+<p>Fetchmail allows to download mails over IMAP/POP3 and uploads it your Mailu mailbox.</p>
+
 <div class="form-check form-check-inline">
   <label class="form-check-label">
     <input class="form-check-input" type="checkbox" name="fetchmail_enabled" value="true">