diff --git a/docs/compose/.env b/docs/compose/.env index cf906b58..218b94d2 100644 --- a/docs/compose/.env +++ b/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 diff --git a/docs/compose/docker-compose.yml b/docs/compose/docker-compose.yml index 2cff9608..2686ee27 100644 --- a/docs/compose/docker-compose.yml +++ b/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: diff --git a/docs/compose/setup.rst b/docs/compose/setup.rst index 3ff1f678..c1a620e6 100644 --- a/docs/compose/setup.rst +++ b/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 ```` scope address. +The bind addresses need to match the public IP addresses assigned to your server. For IPv6 you will need the ```` 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! diff --git a/docs/configuration.rst b/docs/configuration.rst index ec114c97..0bea04b9 100644 --- a/docs/configuration.rst +++ b/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 +``notl`` will cause Mailu not to server any web content! More on :ref:`tls_flavor`. + Mail settings ------------- diff --git a/docs/index.rst b/docs/index.rst index 98825ab6..0808010c 100644 --- a/docs/index.rst +++ b/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 diff --git a/setup/templates/steps/compose/02_services.html b/setup/templates/steps/compose/02_services.html index 11e7a14e..a78a3f62 100644 --- a/setup/templates/steps/compose/02_services.html +++ b/setup/templates/steps/compose/02_services.html @@ -1,13 +1,13 @@ {% call macros.panel("info", "Step 3 - pick some features") %}

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.

- -

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.

+interface, Web email clients, antispam, antivirus, etc. +In this section you can enable the services to you liking.

+

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.

@@ -26,10 +26,9 @@ accessing messages for beginner users.

-

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).

+

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.

+

A Webdav server exposes a Dav interface over HTTP so that clients can store +contacts or calendars using the mail account.

+
+

Fetchmail allows to download mails over IMAP/POP3 and uploads it your Mailu mailbox.

+
-

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).

+

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.

+

A Webdav server exposes a Dav interface over HTTP so that clients can store +contacts or calendars using the mail account.

+
+

Fetchmail allows to download mails over IMAP/POP3 and uploads it your Mailu mailbox.

+