Import the documentation from the wiki

2017-11-01 20:12:17 +01:00
parent ac53b3ed97
commit dc2f1280ed
12 changed files with 654 additions and 25 deletions
--- a/docs/compose/requirements.md
+++ b/docs/compose/requirements.md
@@ -0,0 +1,112 @@
+Docker compose requirements
+===========================
+
+Hardware considerations
+-----------------------
+
+You should make sure that your hardware (virtual or physical) is compatible with
+the latest Linux kernel. Also, you should have at least 2GB of total memory and
+1GB of free memory when running Mailu.
+
+Pick a distribution
+-------------------
+
+The mail server runs as a set of Docker containers. It is thus almost agnostic
+of the underlying operating system as long as a fairly recent Linux kernel is
+running and the Docker API (>= 1.11) is available.
+
+Because most of our tests run on Debian Jessie and Debian Stretch, we recommend
+one of these for the base system. Mailu should however be able to run on
+any of the [officially supported distributions](https://docs.docker.com/engine/installation/).
+
+For the purpose of this guide, all examples are based on Debian Stretch. The
+differences with other system will hardly be noticeable however.
+
+Install the distribution
+------------------------
+
+First, install Debian Stretch from the *netinstall* CD image. When installing,
+make sure that you either:
+
+ - setup a root *ext4* partition,
+ - or setup a root *btrfs* partition,
+ - or leave enough unpartitionned space for a dedicated *ext4* or *btrfs*
+   partition.
+
+If you chose to create a dedicated partition, simply mount it to
+``/var/lib/docker``. You could also create a separate partition (*ext4* is a
+sane default)  ans mount it to ``/mailu`` for storing e-mail data.
+
+Docker supports *AUFS* over *ext4* and *btrfs* as stable storage drivers.
+Other filesystems are supported such as *OverlayFS*. If you know what you are
+doing, you should go for it.
+
+Mailu uses Docker port forwarding from the host to make services
+available to external users. First, your host should have a public IP address
+configured (see ``/etc/network/interfaces``) or your router should
+forward connections to its internal IP address. Due to spam problems and
+reputation services, it
+is highly recommended that you use a dedicated IP address for your mail server
+and that you have a dedicated hostname with forward and reverse DNS entries
+for this IP address.
+
+Also, your host must not listen on ports ``25``, ``80``, ``110``, ``143``,
+``443``, ``465``, ``587``, ``993`` or ``995`` as these are used by Mailu
+services. Therefore, you should disable or uninstall any program that is
+listening on these ports (or have them listen on a different port). For
+instance, on a default Debian install:
+
+```
+apt-get autoremove --purge exim4 exim4-base
+```
+
+Finally, Docker relies heavily on ``iptables`` for port forwardings. You
+should use ``iptables-persistent`` (or any equivalent tool on other
+systems) for managing persistent rules. If you were brave enough to switch to
+``nftables``, you will have to rollback until official support is released
+by Docker or setup your own rulesets.
+
+Install Docker
+--------------
+
+Mailu relies on some of the latest Docker features. Therefore, you should
+install Docker from the official repositories instead of your distribution
+ones.
+
+The Docker website is full of [detailed instructions](https://docs.docker.com/engine/installation/)
+about setting up a proper Docker install. Default configuration should be
+suited for Mailu.
+
+Additionally, you must install ``docker-compose`` by following the instructions
+from the [Docker website](https://docs.docker.com/compose/). Compose is a
+management tool for Docker, especially suited for multiple containers systems
+like Mailu.
+
+Once everything is setup, you should be able to run the following commands
+(exact version numbers do not matter):
+
+```
+$ docker version
+Client:
+ Version:      1.11.2
+ API version:  1.23
+ Go version:   go1.6.2
+ Git commit:   b9f10c9
+ Built:        Sun Jun  5 23:17:55 2016
+ OS/Arch:      linux/amd64
+
+Server:
+ Version:      1.11.1
+ API version:  1.23
+ Go version:   go1.6.2
+ Git commit:   5604cbe
+ Built:        Mon May  2 00:06:51 2016
+ OS/Arch:      linux/amd64
+
+$ docker-compose version
+docker-compose version 1.7.1, build 6c29830
+docker-py version: 1.8.1
+CPython version: 3.5.1
+OpenSSL version: OpenSSL 1.0.2h  3 May 2016
+```
+
--- a/docs/compose/setup.md
+++ b/docs/compose/setup.md
@@ -0,0 +1,124 @@
+Docker Compose setup
+====================
+
+Prepare the environment
+-----------------------
+
+Mailu will store all of its persistent data in a path of your choice
+(``/mailu`` by default) simply create the directory and move there:
+
+```
+mkdir /mailu
+cd /mailu
+```
+
+Download the initial configuration file
+---------------------------------------
+
+Docker Compose configuration is stored in a file named ``docker-compose.yml``.
+Additionally, Mailu relies on an environment file for various settings.
+Download the proper template files from the git repository. For `stable`:
+
+```
+wget -O docker-compose.yml https://raw.githubusercontent.com/Mailu/Mailu/stable/docker-compose.yml.dist
+wget -O .env https://raw.githubusercontent.com/Mailu/Mailu/stable/.env.dist
+```
+
+For the latest version (replace with version number otherwise):
+
+```
+wget -O docker-compose.yml https://raw.githubusercontent.com/Mailu/Mailu/master/docker-compose.yml.dist
+wget -O .env https://raw.githubusercontent.com/Mailu/Mailu/master/.env.dist
+```
+
+Then open the ``.env`` file to setup the mail server. Modify the ``ROOT`` setting
+to match your setup directory if different from ``/mailu``.
+
+Mdify the ``VERSION`` configuration in the ``.env`` file to reflect the version you picked..
+
+Set the common configuration values
+-----------------------------------
+
+Open the ``.env`` file and set configuration settings after reading the configuration
+documentation. Some settings are specific to the Docker Compose setup.
+
+Modify ``BIND_ADDRESS4`` to match the public IP address assigned to your server.
+This address should be configured on one of the network interfaces of the server.
+If the address is not configured directly (NAT) on any of the network interfaces or if
+you would simply like the server to listen on all interfaces, use ``0.0.0.0``.
+
+Modify ``BIND_ADDRESS6`` to match the public IPv6 address assigned to your server.
+The behavior is identical to ``BIND_ADDRESS4``.
+
+Set the `TLS_FLAVOR` to one of the following
+values:
+- `cert` is the default and requires certificates to be setup manually;
+- `letsencrypt` will use the Letsencrypt! CA to generate automatic ceriticates;
+- `notls` will disable TLS, this is not recommended except for testing.
+
+Enable optional features
+------------------------
+
+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 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 ``EXPOSE_ADMIN`` variable accordingly:
+
+- ``yes`` will expose the admin interface in ``/admin``;
+- ``no`` (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 or memory for ClamAV to load its signature
+database.
+
+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.
+
+If you set `TLS_FLAVOR` to `cert` or if then you must create a `certs` directory
+in your root path and setup a key-certificate pair there:
+ - ``cert.pem`` contains the certificate,
+ - ``key.pem`` contains the key pair.
+
+Start Mailu
+-----------
+
+You may now start Mailu. Move the to the Mailu directory and run:
+
+```
+docker-compose up -d
+```
+
+Finally, you must create the initial admin user account:
+
+```
+docker-compose run --rm admin python manage.py admin root example.net password
+```
+
+This will create a user named ``root@example.net`` with password ``password`` and administration privileges. Connect to the Web admin interface and change the password to a strong one.