docker/mailu
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge branch 'master' into refactor-config

Browse Source
This commit is contained in:
kaiyou
2018-11-08 21:43:05 +01:00
parent 30716b8bdf 5c24390114
commit 5b769e23da
111 changed files with 2696 additions and 1098 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
docs/Dockerfile
View File

@@ -2,13 +2,21 @@ FROM python:3-alpine
COPY requirements.txt /requirements.txt
ARG version=master
ENV VERSION=$version
RUN pip install -r /requirements.txt \
&& apk add --no-cache nginx \
&& apk add --no-cache nginx curl \
&& mkdir /run/nginx
COPY ./nginx.conf /etc/nginx/conf.d/default.conf
COPY . /docs
RUN sphinx-build /docs /build
RUN mkdir -p /build/$VERSION \
&& sphinx-build /docs /build/$VERSION
CMD nginx -g "daemon off;"
EXPOSE 80/tcp
CMD nginx -g "daemon off;"
HEALTHCHECK CMD curl -f -L http://localhost/ || exit 1

9
docs/_templates/layout.html vendored
View File

@@ -1,2 +1,9 @@
{% set version=github_version %}
{% extends "!layout.html" %}
{% block document %}
{% if version != stable_version %}
<div class="wy-alert info">
<p>You are currently browsing documentation for the <b>{{ version }}</b> branch. Documentation for the stable <b>{{ stable_version }}</b> branch can be found <a href="/{{ stable_version }}/">here</a>.</p>
</div>
{% endif %}
{{ super() }}
{% endblock %}

4
docs/_templates/page.html vendored
View File

@@ -1,4 +0,0 @@
{%- extends "layout.html" %}
{% block body %}
{{ body|replace("VERSION_TAG", version) }}
{% endblock %}

16
docs/_templates/versions.html vendored Normal file
View File

@@ -0,0 +1,16 @@
<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
<span class="rst-current-version" data-toggle="rst-current-version">
<span class="fa fa-book"> Versions</span>
v: {{ version }}
<span class="fa fa-caret-down"></span>
</span>
<div class="rst-other-versions">
<dl>
<dt>{{ _('Versions') }}</dt>
{% for slug, url in versions %}
<dd><a href="{{ url }}">{{ slug }}</a></dd>
{% endfor %}
</dl>
</div>
</div>

2
docs/cli.rst
View File

@@ -39,7 +39,7 @@ primary difference with simple `user` command is that password is being imported
.. code-block:: bash
docker-compose exec admin flask mailu user --hash_scheme='SHA512-CRYPT' myuser example.net '$6$51ebe0cb9f1dab48effa2a0ad8660cb489b445936b9ffd812a0b8f46bca66dd549fea530ce'
docker-compose run --rm admin python manage.py user --hash_scheme='SHA512-CRYPT' myuser example.net '$6$51ebe0cb9f1dab48effa2a0ad8660cb489b445936b9ffd812a0b8f46bca66dd549fea530ce'
user_delete
------------

4
docs/compose/.env
View File

@@ -130,8 +130,8 @@ LOG_DRIVER=json-file
COMPOSE_PROJECT_NAME=mailu
# Default password scheme used for newly created accounts and changed passwords
# (value: BLF-CRYPT, SHA512-CRYPT, SHA256-CRYPT, MD5-CRYPT, CRYPT)
PASSWORD_SCHEME=BLF-CRYPT
# (value: PBKDF2, BLF-CRYPT, SHA512-CRYPT, SHA256-CRYPT)
PASSWORD_SCHEME=PBKDF2
# Header to take the real ip from
REAL_IP_HEADER=

13
docs/conf.py
View File

@@ -2,6 +2,8 @@
# -*- coding: utf-8 -*-
#
import os
extensions = ['sphinx.ext.imgmath', 'sphinx.ext.viewcode']
templates_path = ['_templates']
source_suffix = '.rst'
@@ -9,9 +11,9 @@ master_doc = 'index'
project = 'Mailu'
copyright = '2018, Mailu authors'
author = 'Mailu authors'
version = release = 'latest'
version = release = os.environ.get('VERSION', 'master')
language = None
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'Dockerfile', 'docker-compose.yml']
pygments_style = 'sphinx'
todo_include_todos = False
html_theme = 'sphinx_rtd_theme'
@@ -33,6 +35,11 @@ html_context = {
'display_github': True,
'github_user': 'mailu',
'github_repo': 'mailu',
'github_version': 'master',
'github_version': version,
'stable_version': '1.5',
'versions': [
('1.5', '/1.5/'),
('master', '/master/')
],
'conf_py_path': '/docs/'
}

202
docs/contributors/environment.rst
View File

@@ -1,20 +1,117 @@
Development environment
=======================
Git
---
Before any partaking in development, you will need to fork the Mailu repository on GitHub.
For this you will need a `GitHub`_ account. GitHub has excellent documentation on:
#. How to `fork a repo`_ and set upstream (Mailu);
#. Keeping your fork `synced`_;
#. Sending a `pull request`_.
Working on Mailu usually requires you to clone (download) your fork to your work station and
create a branch. From here you can work on Mailu. When done, create a commit and push the
branch to your GitHub repository. Then, on GitHub you can create a "pull request".
Please make sure you have read the :ref:`git_workflow` section of the *Development guidelines*
before submitting any pull requests.
.. note:: It is strongly advised to **never** modify the ``master`` branch of your fork.
This will make it impossible to sync your fork with upstream and creating new (and clean)
branches! This includes never merging other branches from yourself or other users into your
``master``. If you want to do that, create a separate branch for it.
Short work flow example
```````````````````````
.. code-block:: bash
git clone https://github.com/<YOUR_USERNAME>/Mailu.git
cd Mailu
git add remote upstream https://github.com/Mailu/Mailu.git
git checkout -b fix-something master
Work on the code as desired. Before doing a commit, you should at least build
and run the containers. Keep reading this guide for more information. After this,
continue to commit and send a PR.
.. code-block:: bash
git commit -a
#Enter commit message in editor, save and close.
git push --set-upstream origin fix-something
Now you can go to your GitHub page, select the new branch and "send pull request".
Updating your fork
``````````````````
The Mailu ``master`` branch is an ever evolving target. It is important that newly
created branches originate from the latest ``upstream/master``. In order to do so, you will
need to `sync your fork`__:
.. code-block:: bash
git fetch --all
git checkout master
git merge upstream/master
If you kept your master branch clean, this should fast-forward it to the latest upstream version.
Likewise, if you worked on your branch for a longer amount of time, it is advised to merge the
latest ``upstream/master`` into the branch.
.. code-block:: bash
git checkout my-old-branch
git merge upstream/master
Now, git won't fast forward but write a merge commit. Typically you can accept the commit message
presented. Read the output if there are any merge conflicts. In ``git status`` you can find the files
that need editing to have the desired contents. Also, it will tell you how to mark them as resolved.
Optionally, you can ``git push`` after any of above merges to propagate them to GitHub.
__ `synced`_
Bad habits
```````````
Some bad habits from users that we are sometimes confronted with. Please refrain yourself from:
- ``git reset REF`` and ``git push --force`` after submitting a PR.
- Merge a branch (other then master) into yours and submitting a PR before that other branch got
merged into master. It will cause you to submit commits someone else wrote and are probably outside
the subject of your PR. (There are valid cases however, but take care!)
- ``git reset REF`` after merging ``upstream/master`` into your branch. It will unstage **all**
changed files that where updated in the merge. Your will have to clean up all of them
(don't delete!) using ``git checkout -- <file>``. And take care not to do that to the files you
have modified. However, it can be that the merge modified some other lines then yours. You'll have
to make sure there will be no conflicts when you are submitting this messed up branch to Mailu! You
get the point, I hope.
- ``git rebase`` on a branch that is pull-requested. Others will not be able to see you modified the
branch and it messes with the order of commits, compared to a merge. It might break things after we
have conducted tests.
.. _`GitHub`: https://github.com/
.. _`fork a repo`: https://help.github.com/articles/fork-a-repo/
.. _`synced`: https://help.github.com/articles/syncing-a-fork/
.. _`pull request`: https://help.github.com/articles/about-pull-requests/
Docker containers
-----------------
The development environment is quite similar to the production one. You should always use
the ``master`` version when developing.
The development environment is quite similar to the production one.
Building images
```````````````
We supply a separate ``test/build.yml`` file for
convenience. To build all Mailu containers:
We supply a separate ``test/build.yml`` file for convenience.
After cloning the git repository to your workstation, you can build the images:
.. code-block:: bash
cd Mailu
docker-compose -f tests/build.yml build
The ``build.yml`` file has two variables:
@@ -73,10 +170,96 @@ Finally, if you need to install packages inside the containers for debugging:
docker-compose exec admin apk add --no-cache package-name
Reviewing
---------
System requirements
```````````````````
Reviewing pull requests requires some additional git setup. First, for 90% of the review jobs,
you will need a PC or server that can expose all Mailu ports to the outside world. Also, a valid
domain name would be required. This can be a simple free DynDNS account. Do not use a production
server, as there are cases where data corruption occurs and you need to delete the ``/mailu``
directory structure.
If you do no posses the resources, but want to become an involved tester/reviewer.
Please contact `muhlemmer on Matrix`_.
He can provide access to a testing server, if a thrust relation can be established.
.. _`muhlemmer on Matrix`: https://matrix.to/#/@muhlemmer:matrix.org
Preparations
````````````
#. Setup `Git`_ the same way as on a development PC. It is advised to keep ``origin`` as your
own repository and ``upstream`` as the one from Mailu. This will avoid confusion;
#. You will need a ``docker-compose.yml`` and ``.env``, set up for the test server;
#. Make sure that the build ``$VERSION`` corresponds with those files.
Add the sender
``````````````
Replace ``<SENDER>`` with the repository name the PR is sent from.
.. code-block:: bash
git remote add <SENDER> https://github.com/<SENDER>/Mailu.git
Merge conflicts
```````````````
Before proceeding, check the PR page in the bottom. It should not indicate a merge conflict.
If there are merge conflicts, you have 2 options:
#. Do a review "request changes" and ask the author to resolve the merge conflict.
#. Solve the merge conflict yourself on Github, using the web editor.
If it can't be done in the web editor, go for option 1. Unless you want to go through the trouble of
importing the branch into your fork, do the merge and send a PR to the repository of the *sender*.
Merge the PR locally
```````````````````````
When someone sends a PR, you need merge his PR into master locally. This example will put you in a
"detached head" state and do the merge in that state. Any commits done in this state will be lost
forever when you checkout a "normal" branch. This is exactly what we want, as we do not want to mess
with our repositories. This is just a test run.
The following must be done on every PR or after every new commit to an existing PR:
1. Fetch the latest status of all the remotes.
2. List all local and remote available branches (this is not needed, but very helpful at times)
3. Checkout ``upstream/master``
4. Merge ``upstream/master`` with ``SENDER/branch``
.. code-block:: bash
git fetch --all
git checkout upstream/master
# ...You are in 'detached HEAD' state.... (bla bla bla)
git branch -a
# Hit `q` to exit the viewer, if it was opened. Uses arrows up/down for scrolling.
git merge kaiyou/fix-sender-checks
If git opens a editor for a commit message just save and exit as-is. If you have a merge conflict,
see above and do the complete procedure from ``git fetch`` onward again.
Test
````
You can now build and run the containers for testing. See the "`Docker containers`_" section for
instructions. Play around. See if (external) mails work. Check for whatever functionality the PR is
trying to fix. When happy, you can approve the PR. When running into failures, mark the review as
"request changes" and try to provide as much as possible details on the failure.
(Logs, error codes form clients etc).
.. note:: Github marks positive reviews as obsolete when a new commit is added to a PR.
This requires a new review from your side.
Web administration
------------------
The administration Web interface requires a proper dev environment that can easily be setup using ``virtualenv`` (make sure you are using Python 3) :
The administration Web interface requires a proper dev environment that can easily be setup using
``virtualenv`` (make sure you are using Python 3) :
.. code-block:: bash
@@ -105,7 +288,8 @@ of the screen, that you can open to access query details, internal variables, et
Documentation
-------------
Documentation is maintained in the ``docs`` directory and are maintained as `reStructuredText`_ files. It is possible to run a local documentation server for reviewing purposes, using Docker:
Documentation is maintained in the ``docs`` directory and are maintained as `reStructuredText`_
files. It is possible to run a local documentation server for reviewing purposes, using Docker:
.. code-block:: bash
@@ -113,8 +297,10 @@ Documentation is maintained in the ``docs`` directory and are maintained as `reS
docker build -t docs docs
docker run -p 127.0.0.1:8080:80 docs
You can now read the local documentation by navigating to http://localhost:8080.
In a local build Docker always assumes the version to be master.
You can read the local documentation by navigating to http://localhost:8080/master.
.. note:: After modifying the documentation, the image needs to be rebuild and the container restarted for the changes to become visible.
.. note:: After modifying the documentation, the image needs to be rebuild and the container
restarted for the changes to become visible.
.. _`reStructuredText`: http://docutils.sourceforge.net/rst.html

2
docs/contributors/guide.rst
View File

@@ -13,6 +13,8 @@ Docker best practices and be as generic as possible :
- interesting settings should be available as environment variables
- base images should be well-trusted (officiel Alpine or Debian for instance).
.. _git_workflow:
Git workflow
------------

21
docs/docker-compose.yml Normal file
View File

@@ -0,0 +1,21 @@
version: '3'
services:
docs_master:
image: mailu/docs:master
labels:
- traefik.enable=true
- traefik.port=80
- traefik.main.frontend.rule=Host:${hostname};PathPrefix:/master/
docs_15:
image: mailu/docs:1.5
labels:
- traefik.enable=true
- traefik.port=80
- traefik.root.frontend.redirect.regex=.*
- traefik.root.frontend.redirect.replacement=/1.5/
- traefik.root.frontend.rule=Host:${hostname};PathPrefix:/
- traefik.main.frontend.rule=Host:${hostname};PathPrefix:/1.5/

276
docs/faq.rst Normal file
View File

@@ -0,0 +1,276 @@
Frequently asked questions
==========================
Informational
-------------
Where to ask questions?
```````````````````````
First, please read this FAQ to check if your question is listed here.
Simple questions best fit in our `Matrix`_ room.
For more complex questions, you can always open a `new issue`_ on GitHub.
We actively monitor the issues list.
My installation is broken!
``````````````````````````
We're sorry to hear that. Please check for common mistakes and troubleshooting
advice in the `Technical issues`_ section of this page.
I think I found a bug!
``````````````````````
If you did not manage to solve the issue using this FAQ and there is not any
`open issues`_ describing the same problem, you can continue to open a
`new issue`_ on GitHub.
I want a new feature or enhancement!
````````````````````````````````````
Great! We are always open for suggestions. We currently maintain two tags:
- `Enhancement issues`_: Typically used for optimization of features in the project.
- `Feature request issues`_: For implementing new functionality,
plugins and applications.
Please check if your idea (or something similar) is already mentioned there.
If there is one open, you can choose to vote with a thumbs up, so we can
estimate the popular demand. Please refrain from writing comments like
*"me too"* as it clobbers the actual discussion.
If you can't find anything similar, you can open a `new issue`_.
Please also share (where applicable):
- Use case: how does this improve the project?
- Any research done on the subject. Perhaps some links to upstream website,
reference implementations etc.
Why does my feature/bug take so long to solve?
``````````````````````````````````````````````
You should be aware that creating, maintaining and expanding a mail server
distribution requires a lot of effort. Mail servers are highly exposed to hacking attempts,
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;
#. We use Travis-CI for some very basic building and testing;
#. The pull request needs to be code-reviewed and tested by at least two members
from the contributors team.
Please consider that this project is mostly developed in people their free time.
We thank you for your understanding and patience.
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
among the developers.
It is not yet possible to pay for a specific feature. We don't have
any bounty system implemented. Feel free to come with suggestions in
our ongoing `project management`_ discussion issue.
.. _`Matrix`: https://matrix.to/#/#mailu:tedomum.net
.. _`open issues`: https://github.com/Mailu/Mailu/issues
.. _`new issue`: https://github.com/Mailu/Mailu/issues/new
.. _`Enhancement issues`: https://github.com/Mailu/Mailu/issues?q=is%3Aissue+is%3Aopen+label%3Atype%2Fenhancement
.. _`Feature request issues`: https://github.com/Mailu/Mailu/issues?q=is%3Aopen+is%3Aissue+label%3Atype%2Ffeature
.. _`patreon`: https://patreon.com/kaiyou
.. _`project management`: https://github.com/Mailu/Mailu/issues/508
Deployment related
------------------
How does Mailu scale up?
````````````````````````
Recent works allow Mailu to be deployed in Docker Swarm and Kubernetes.
This means it can be scaled horizontally. For more information, refer to :ref:`kubernetes`
or the `Docker swarm howto`_.
*Issue reference:* `165`_, `520`_.
How to achieve HA / failover?
`````````````````````````````
The mailboxes and databases for Mailu are kept on the host filesystem under ``$ROOT/``.
For making the **storage** highly available, all sorts of techniques can be used:
- Local raid-1
- btrfs in raid configuration
- Distributed network filesystems such as GlusterFS or CEPH
Note that no storage HA solution can protect against incidental deletes or file corruptions.
Therefore it is advised to create backups on a regular base!
A backup MX can be configured as **failover**. For this you need a separate server running
Mailu. On that server, your domains will need to be setup as "Relayed domains", pointing
to you main server. MX records for the mail domains with a higher priority number will have
to point to this server. Please be aware that a backup MX can act as a `spam magnet`_.
For **service** HA, please see: `How does Mailu scale up?`_
*Issue reference:* `177`_, `591`_.
.. _`spam magnet`: https://blog.zensoftware.co.uk/2012/07/02/why-we-tend-to-recommend-not-having-a-secondary-mx-these-days/
Can I run Mailu without host iptables?
``````````````````````````````````````
When disabling iptables in docker, its forwarding proxy process takes over.
This creates the situation that every incoming connection on port 25 seems to come from the
local network (docker's 172.17.x.x) and is accepted. This causes an open relay!
For that reason we do **not** support deployment on Docker hosts without iptables.
*Issue reference:* `332`_.
How can I override settings?
````````````````````````````
Postfix, dovecot and Rspamd support overriding configuration files. Override files belong in
``$ROOT/overrides``. Please refer to the official documentation of those programs for the
correct syntax. The following file names will be taken as override configuration:
- `Postfix`_ - ``postfix.cf``;
- `Dovecot`_ - ``dovecot.conf``;
- `Rspamd`_ - All files in the ``rspamd`` sub-directory.
.. _`Postfix`: http://www.postfix.org/postconf.5.html
.. _`Dovecot`: https://wiki.dovecot.org/ConfigFile
.. _`Rspamd`: https://www.rspamd.com/doc/configuration/index.html
.. _`Docker swarm howto`: https://github.com/Mailu/Mailu/tree/master/docs/swarm/master
.. _`165`: https://github.com/Mailu/Mailu/issues/165
.. _`177`: https://github.com/Mailu/Mailu/issues/177
.. _`332`: https://github.com/Mailu/Mailu/issues/332
.. _`520`: https://github.com/Mailu/Mailu/issues/520
.. _`591`: https://github.com/Mailu/Mailu/issues/591
Technical issues
----------------
In this section we are trying to cover the most common problems our users are having.
If your issue is not listed here, please consult issues with the `troubleshooting tag`_.
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`_.
Do you support Fail2Ban?
````````````````````````
Fail2Ban is not included in Mailu. Fail2Ban needs to modify the host's IP tables in order to
ban the addresses. We consider such a program should be run on the host system and not
inside a container. The ``front`` container does use authentication rate limiting to slow
down brute force attacks.
We *do* provide a possibility to export the logs from the ``front`` service to the host.
For this you need to set ``LOG_DRIVER=journald`` or ``syslog``, depending on the log
manager of the host. You will need to setup the proper Regex in the Fail2Ban configuration.
Be aware that webmail authentication appears to come from the Docker network,
so don't ban those addresses!
*Issue reference:* `85`_, `116`_, `171`_, `584`_, `592`_.
Users can't change their password from webmail
``````````````````````````````````````````````
All users have the abilty to login to the admin interface. Non-admin users
have only restricted funtionality such as changing their password and the
spam filter weight settings.
*Issue reference:* `503`_.
.. _`troubleshooting tag`: https://github.com/Mailu/Mailu/issues?utf8=%E2%9C%93&q=label%3Afaq%2Ftroubleshooting
.. _`85`: https://github.com/Mailu/Mailu/issues/85
.. _`116`: https://github.com/Mailu/Mailu/issues/116
.. _`171`: https://github.com/Mailu/Mailu/issues/171
.. _`426`: https://github.com/Mailu/Mailu/issues/426
.. _`503`: https://github.com/Mailu/Mailu/issues/503
.. _`584`: https://github.com/Mailu/Mailu/issues/584
.. _`592`: https://github.com/Mailu/Mailu/issues/592
.. _`615`: https://github.com/Mailu/Mailu/issues/615

3
docs/index.rst
View File

@@ -44,6 +44,7 @@ the version of Mailu that you are running.
general
features
faq
releases
demo
@@ -55,7 +56,7 @@ the version of Mailu that you are running.
configuration
compose/requirements
compose/setup
kubernetes/stable/index
kubernetes/mailu/index
dns
reverse

157
docs/kubernetes/1.6/README.md
View File

@@ -1,157 +0,0 @@
# Install Mailu master on kubernetes
## Prequisites
### Structure
There's chosen to have a double NGINX stack for Mailu, this way the main ingress can still be used to access other websites/domains on your cluster. This is the current structure:
- `NGINX Ingress controller`: Listens to the nodes ports 80 & 443 and directly forwards all TCP traffic on the E-amail ports (993,143,25,587,...). This is because this `DaemonSet` already consumes ports 80 & 443 and uses `hostNetwork: true`
- `Cert manager`: Creates automatic Lets Encrypt certificates based on an `Ingress`-objects domain name.
- `Mailu NGINX Front container`: This container receives all the mail traffic forwarded from the ingress controller. The web traffic is also forwarded based on an ingress
- `Mailu components`: All Mailu components are split into separate files to make them more
### What you need
- A working Kubernetes cluster (tested with 1.10.5)
- A working [cert-manager](https://github.com/jetstack/cert-manager) installation
- A working nginx-ingress controller needed for the lets-encrypt certificates. You can find those files in the `nginx` subfolder
#### Cert manager
The `Cert-manager` is quite easy to deploy using Helm when reading the [docs](https://cert-manager.readthedocs.io/en/latest/getting-started/2-installing.html).
After booting the `Cert-manager` you'll need a `ClusterIssuer` which takes care of all required certificates through `Ingress` items. An example:
```yaml
apiVersion: certmanager.k8s.io/v1alpha1
kind: ClusterIssuer
metadata:
name: letsencrypt-prod
spec:
acme:
email: something@example.com
http01: {}
privateKeySecretRef:
key: ""
name: letsencrypt-stage
server: https://acme-v02.api.letsencrypt.org/directory
```
## Deploying Mailu
All manifests can be found in the `mailu` subdirectory. All commands below need to be run from this subdirectory
### Personalization
- All services run in the same namespace, currently `mailu-mailserver`. So if you want to use a different one, change the `namespace` value in **every** file
- Check the `storage-class` field in the `pvc.yaml` file, you can also change the sizes to your liking. Note that you need `RWX` (read-write-many) and `RWO` (read-write-once) storageclasses.
- Check the `configmap.yaml` and adapt it to your needs. Be sure to check the kubernetes DNS values at the end (if you use a different namespace)
- Check the `ingress-ssl.yaml` and change it to the domain you want (this is for the kubernetes ingress controller, it will forward to `mailu/nginx` a.k.a. the `front` pod)
## Installation
First run the command to start Mailu:
```bash
kubectl create -f rbac.yaml
kubectl create -f configmap.yaml
kubectl create -f pvc.yaml
kubectl create -f ingress-ssl.yaml
kubectl create -f redis.yaml
kubectl create -f front.yaml
kubectl create -f webmail.yaml
kubectl create -f imap.yaml
kubectl create -f security.yaml
kubectl create -f smtp.yaml
kubectl create -f fetchmail.yaml
kubectl create -f admin.yaml
kubectl create -f webdav.yaml
```
## Create the first admin account
When the cluster is online you need to create you master user to access `https://mail.example.com/admin`.
Enter the main `admin` pod to create the root account:
```bash
kubectl -n mailu-mailserver get po
kubectl -n mailu-mailserver exec -it mailu-admin-.... /bin/sh
```
And in the pod run the following command. The command uses following entries:
- `admin` Make it an admin user
- `root` The first part of the e-mail adres (ROOT@example.com)
- `example.com` the domain appendix
- `password` the chosen password for the user
```bash
flask mailu admin root example.com password
```
Now you should be able to login on the mail account: `https://mail.example.com/admin`
## Adaptations
### Postfix
I noticed you need an override for the `postfix` server in order to be able to send mail. I noticed Google wasn't able to deliver mail to my account and it had to do with the `smtpd_authorized_xclient_hosts` value in the config file. The config can be read [here](https://github.com/hacor/Mailu/blob/master/core/postfix/conf/main.cf#L35) and is pointing to a single IP of the service. But the requests come from the host IPs (the NGINX Ingress proxy) and they don't use the service specific IP.
Enter the `postfix` pod:
```bash
kubectl -n mailu-mailserver get po
kubectl -n mailu-mailserver exec -it mailu-smtp-.... /bin/sh
```
Now you're in the pod, create an override file like so:
```bash
vi /overrides/postfix.cf
```
And give it the following contents, off course replacing `10.2.0.0/16` with the CIDR of your pod range. This way the NGINX pods can also restart and your mail server will still operate
```bash
not_needed = true
smtpd_authorized_xclient_hosts = 10.2.0.0/16
```
The first line seems stupid, but is needed because its pasted after a #, so from the second line we're really in action.
Save and close the file and exit. Now you need to delete the pod in order to recreate the config file.
```bash
kubectl -n mailu-mailserver delete po/mailu-smtp-....
```
### Dovecot
- If you are using Dovecot on a shared file system (Glusterfs, NFS,...), you need to create a special override otherwise a lot of indexing errors will occur on your Dovecot pod.
- I also higher the number of max connections per IP. Now it's limited to 10.
Enter the dovecot pod:
```bash
kubectl -n mailu-mailserver get po
kubectl -n mailu-mailserver exec -it mailu-imap-.... /bin/sh
```
Create the file `/overrides/dovecot.conf`
```bash
vi /overrides/dovecot.conf
```
And enter following contents:
```bash
mail_nfs_index = yes
mail_nfs_storage = yes
mail_fsync = always
mmap_disable = yes
mail_max_userip_connections=100
```
Save and close the file and delete the imap pod to get it recreated.
```bash
kubectl -n mailu-mailserver delete po/mailu-imap-....
```
Wait for the pod to recreate and you're online!
Happy mailing!
Wait for the pod to recreate and you're online!
Happy mailing!

32
docs/kubernetes/1.6/mailu/ingress-ssl.yaml
View File

@@ -1,32 +0,0 @@
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: mailu-ssl-ingress
namespace: mailu-mailserver
annotations:
kubernetes.io/ingress.class: tectonic
kubernetes.io/tls-acme: "true"
nginx.ingress.kubernetes.io/proxy-body-size: "0"
ingress.kubernetes.io/ssl-redirect: "true"
# Replace letsencrypt-prod with the name of the certificate issuer
certmanager.k8s.io/cluster-issuer: letsencrypt-prod
#ingress.kubernetes.io/rewrite-target: "/"
#ingress.kubernetes.io/app-root: "/ui"
#ingress.kubernetes.io/follow-redirects: "true"
labels:
app: mailu
role: mail
tier: backend
spec:
tls:
- hosts:
- "mail.example.com"
secretName: letsencrypt-certs-all # If unsure how to generate these, check out https://github.com/ployst/docker-letsencrypt
rules:
- host: "mail.example.com"
http:
paths:
- path: "/"
backend:
serviceName: front
servicePort: 80

0
docs/kubernetes/1.6/mailu/static-ips.yaml
View File

86
docs/kubernetes/mailu/admin-ingress.yaml Normal file
View File

@@ -0,0 +1,86 @@
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: mailu-admin-ingress
namespace: mailu-mailserver
annotations:
kubernetes.io/tls-acme: "true"
nginx.ingress.kubernetes.io/proxy-body-size: "0"
certmanager.k8s.io/cluster-issuer: letsencrypt-stage
ingress.kubernetes.io/permanent-redirect: "https://mail.example.com/admin/ui/"
ingress.kubernetes.io/follow-redirects: "true"
labels:
app: mailu
role: mail
tier: backend
spec:
tls:
- hosts:
- "mail.example.com"
secretName: letsencrypt-certs-all # If unsure how to generate these, check out https://github.com/ployst/docker-letsencrypt
rules:
- host: "mail.example.com"
http:
paths:
- path: "/admin"
backend:
serviceName: admin
servicePort: 80
---
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: mailu-admin-ui-ingress
namespace: mailu-mailserver
annotations:
kubernetes.io/tls-acme: "true"
certmanager.k8s.io/cluster-issuer: letsencrypt-stage
ingress.kubernetes.io/rewrite-target: "/ui"
ingress.kubernetes.io/configuration-snippet: |
proxy_set_header X-Forwarded-Prefix /admin;
labels:
app: mailu
role: mail
tier: backend
spec:
tls:
- hosts:
- "mail.example.com"
secretName: letsencrypt-certs-all # If unsure how to generate these, check out https://github.com/ployst/docker-letsencrypt
rules:
- host: "mail.example.com"
http:
paths:
- path: "/admin/ui"
backend:
serviceName: admin
servicePort: 80
---
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: mailu-admin-static-ingress
namespace: mailu-mailserver
annotations:
kubernetes.io/tls-acme: "true"
certmanager.k8s.io/cluster-issuer: letsencrypt-stage
ingress.kubernetes.io/rewrite-target: "/static"
ingress.kubernetes.io/configuration-snippet: |
proxy_set_header X-Forwarded-Prefix /admin;
labels:
app: mailu
role: mail
tier: backend
spec:
tls:
- hosts:
- "mail.example.com"
secretName: letsencrypt-certs-all # If unsure how to generate these, check out https://github.com/ployst/docker-letsencrypt
rules:
- host: "mail.example.com"
http:
paths:
- path: "/admin/static"
backend:
serviceName: admin
servicePort: 80

1
docs/kubernetes/1.6/mailu/admin.yaml → docs/kubernetes/mailu/admin.yaml
View File

@@ -1,4 +1,3 @@
apiVersion: extensions/v1beta1
kind: Deployment
metadata:

28
docs/kubernetes/1.6/mailu/configmap.yaml → docs/kubernetes/mailu/configmap.yaml
View File

@@ -21,7 +21,7 @@
VERSION: "master"
# Set to a randomly generated 16 bytes string
SECRET_KEY: "YourKeyHere"
SECRET_KEY: "MySup3rS3cr3tPas"
# Address where listening ports should bind
BIND_ADDRESS4: "127.0.0.1"
@@ -45,6 +45,14 @@
# Opt-out of statistics, replace with "True" to opt out
DISABLE_STATISTICS: "False"
###################################
# Kubernetes configuration
###################################
# Use Kubernetes Ingress Controller to handle all actions on port 80 and 443
# This way we can make use of the advantages of the cert-manager deployment
KUBERNETES_INGRESS: "true"
###################################
# Optional features
###################################
@@ -71,19 +79,18 @@
# Default: accept messages up to 50MB
MESSAGE_SIZE_LIMIT: "50000000"
# Networks granted relay permissions, make sure that you include your Docker
# internal network (default to 172.17.0.0/16)
# For kubernetes this is the CIDR of the pod network
RELAYNETS: "10.2.0.0/16"
POD_ADDRESS_RANGE: "10.2.0.0/16"
# Will relay all outgoing mails if configured
#RELAYHOST=
# This part is needed for the XCLIENT login for postfix. This should be the POD ADDRESS range
FRONT_ADDRESS: "front.mailu-mailserver.svc.cluster.local"
# This value is needed by the webmail to find the correct imap backend
IMAP_ADDRESS: "imap.mailu-mailserver.svc.cluster.local"
# This value is used by Dovecot to find the Redis server in the cluster
REDIS_ADDRESS: "redis.mailu-mailserver.svc.cluster.local"
# Fetchmail delay
FETCHMAIL_DELAY: "600"
@@ -106,13 +113,16 @@
###################################
# Path to the admin interface if enabled
# Kubernetes addition: You need to change ALL the ingresses, when you want this URL to be different!!!
WEB_ADMIN: "/admin"
# Path to the webmail if enabled
# Currently, this is not used, because we intended to use a different subdomain: webmail.example.com
# This option can be added in a feature release
WEB_WEBMAIL: "/webmail"
# Website name
SITENAME: "AppSynth"
SITENAME: "Mailu"
# Linked Website URL
WEBSITE: "https://example.com"

0
docs/kubernetes/1.6/mailu/fetchmail.yaml → docs/kubernetes/mailu/fetchmail.yaml
View File

58
docs/kubernetes/1.6/mailu/front.yaml → docs/kubernetes/mailu/front.yaml
View File

@@ -1,23 +1,41 @@
apiVersion: extensions/v1beta1
kind: Deployment
apiVersion: apps/v1beta2
kind: DaemonSet
metadata:
name: mailu-front
namespace: mailu-mailserver
labels:
k8s-app: mail-loadbalancer
component: ingress-controller
type: nginx
spec:
replicas: 1
selector:
matchLabels:
k8s-app: mail-loadbalancer
component: ingress-controller
type: nginx
template:
metadata:
labels:
app: mailu-front
role: mail
tier: backend
k8s-app: mail-loadbalancer
component: ingress-controller
type: nginx
spec:
affinity:
nodeAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
nodeSelectorTerms:
- matchExpressions:
- key: node-role.kubernetes.io/node
operator: Exists
hostNetwork: true
nodeSelector:
node-role.kubernetes.io/node: ""
dnsPolicy: ClusterFirstWithHostNet
restartPolicy: Always
terminationGracePeriodSeconds: 60
containers:
- name: front
image: mailu/nginx:latest
image: mailu/nginx:master
imagePullPolicy: Always
envFrom:
- configMapRef:
@@ -26,12 +44,6 @@ spec:
- name: certs
mountPath: /certs
ports:
- name: http
containerPort: 80
protocol: TCP
- name: https
containerPort: 443
protocol: TCP
- name: pop3
containerPort: 110
protocol: TCP
@@ -85,21 +97,15 @@ metadata:
name: front
namespace: mailu-mailserver
labels:
app: mailu-admin
role: mail
tier: backend
k8s-app: mail-loadbalancer
component: ingress-controller
type: nginx
spec:
selector:
app: mailu-front
role: mail
tier: backend
k8s-app: mail-loadbalancer
component: ingress-controller
type: nginx
ports:
- name: http
port: 80
protocol: TCP
- name: https
port: 443
protocol: TCP
- name: pop3
port: 110
protocol: TCP

4
docs/kubernetes/1.6/mailu/imap.yaml → docs/kubernetes/mailu/imap.yaml
View File

@@ -37,8 +37,8 @@ spec:
- containerPort: 4190
resources:
requests:
memory: 500Mi
cpu: 500m
memory: 1Gi
cpu: 1000m
limits:
memory: 1Gi
cpu: 1000m

195
docs/kubernetes/mailu/index.rst Normal file
View File

@@ -0,0 +1,195 @@
.. _kubernetes:
Kubernetes setup
================
Prequisites
-----------
Structure
~~~~~~~~~
There’s chosen to have a double NGINX stack for Mailu, this way the main
ingress can still be used to access other websites/domains on your
cluster. This is the current structure:
- ``NGINX Ingress controller``: Listens to the nodes ports 80 & 443. We have chosen to have a double NGINX stack for Mailu.
- ``Cert manager``: Creates automatic Lets Encrypt certificates based on an ``Ingress``-objects domain name.
- ``Mailu NGINX Front daemonset``: This daemonset runs in parallel with the Nginx Ingress Controller and only listens on all E-mail specific ports (25, 110, 143, 587,...)
- ``Mailu components``: All Mailu components (imap, smtp, security, webmail,...) are split into separate files to make them more handy to use, you can find the ``YAML`` files in this directory
What you need
~~~~~~~~~~~~~
- A working Kubernetes cluster (tested with 1.10.5)
- A working `cert-manager`_ installation
- A working nginx-ingress controller needed for the lets-encrypt
certificates. You can find those files in the ``nginx`` subfolder
Cert manager
^^^^^^^^^^^^
The ``Cert-manager`` is quite easy to deploy using Helm when reading the
`docs`_. After booting the ``Cert-manager`` you’ll need a
``ClusterIssuer`` which takes care of all required certificates through
``Ingress`` items. We chose to provide a ``clusterIssuer`` so you can provide SSL certificates
for other namespaces (different websites/services), if you don't need this option, you can easily change this by
changing ``clusterIssuer`` to ``Issuer`` and adding the ``namespace: mailu-mailserver`` to the metadata.
An example of a production and a staging ``clusterIssuer``:
.. code:: yaml
# This clusterIssuer example uses the staging environment for testing first
apiVersion: certmanager.k8s.io/v1alpha1
kind: ClusterIssuer
metadata:
name: letsencrypt-stage
spec:
acme:
email: something@example.com
http01: {}
privateKeySecretRef:
name: letsencrypt-stage
server: https://acme-staging-v02.api.letsencrypt.org/directory
.. code:: yaml
# This clusterIssuer example uses the production environment
apiVersion: certmanager.k8s.io/v1alpha1
kind: ClusterIssuer
metadata:
name: letsencrypt-prod
spec:
acme:
email: something@example.com
http01: {}
privateKeySecretRef:
name: letsencrypt-prod
server: https://acme-v02.api.letsencrypt.org/directory
**IMPORTANT**: All ``*-ingress.yaml`` files use the ``letsencrypt-stage`` ``clusterIssuer``. If you are ready for production,
change this field in all ``*-ingress.yaml`` files to ``letsencrypt-prod`` or whatever name you chose for the production.
If you choose for ``Issuer`` instead of ``clusterIssuer`` you also need to change the annotation to ``certmanager.k8s.io/issuer`` instead of ``certmanager.k8s.io/cluster-issuer``
Deploying Mailu
---------------
All manifests can be found in the ``mailu`` subdirectory. All commands
below need to be run from this subdirectory
Personalization
~~~~~~~~~~~~~~~
- All services run in the same namespace, currently ``mailu-mailserver``. So if you want to use a different one, change the ``namespace`` value in **every** file
- Check the ``storage-class`` field in the ``pvc.yaml`` file, you can also change the sizes to your liking. Note that you need ``RWX`` (read-write-many) and ``RWO`` (read-write-once) storageclasses.
- Check the ``configmap.yaml`` and adapt it to your needs. Be sure to check the kubernetes DNS values at the end (if you use a different namespace)
- Check the ``*-ingress.yaml`` files and change it to the domain you want (this is for the kubernetes ingress controller to handle the admin, webmail, webdav and auth connections)
Installation
------------
Boot the Mailu components
~~~~~~~~~~~~~~~~~~~~~~~~~
To start Mailu, run the following commands from the ``docs/kubernetes/mailu`` directory
.. code-block:: bash
kubectl create -f rbac.yaml
kubectl create -f configmap.yaml
kubectl create -f pvc.yaml
kubectl create -f redis.yaml
kubectl create -f front.yaml
kubectl create -f webmail.yaml
kubectl create -f imap.yaml
kubectl create -f security.yaml
kubectl create -f smtp.yaml
kubectl create -f fetchmail.yaml
kubectl create -f admin.yaml
kubectl create -f webdav.yaml
kubectl create -f admin-ingress.yaml
kubectl create -f webdav-ingress.yaml
kubectl create -f security-ingress.yaml
kubectl create -f webmail-ingress.yaml
Create the first admin account
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When the cluster is online you need to create you master user to access https://mail.example.com/admin
Enter the main ``admin`` pod to create the root account:
.. code-block:: bash
kubectl -n mailu-mailserver get po
kubectl -n mailu-mailserver exec -it mailu-admin-.... /bin/sh
And in the pod run the following command. The command uses following entries:
.. code-block:: bash
python manage.py admin root example.com password
- ``admin`` Make it an admin user
- ``root`` The first part of the e-mail adres (ROOT@example.com)
- ``example.com`` the domain appendix
- ``password`` the chosen password for the user
Now you should be able to login on the mail account: https://mail.example.com/admin
Adaptations
-----------
Dovecot
~~~~~~~
- If you are using Dovecot on a shared file system (Glusterfs, NFS,...), you need to create a special override otherwise a lot of indexing errors will occur on your Dovecot pod.
- I also higher the number of max connections per IP. Now it's limited to 10.
Enter the dovecot pod:
.. code:: bash
kubectl -n mailu-mailserver get po
kubectl -n mailu-mailserver exec -it mailu-imap-.... /bin/sh
Create the file ``overrides/dovecot.conf``
.. code:: bash
vi /overrides/dovecot.conf
And enter following contents:
.. code:: bash
mail_nfs_index = yes
mail_nfs_storage = yes
mail_fsync = always
mmap_disable = yes
mail_max_userip_connections=100
Save and close the file and delete the imap pod to get it recreated.
.. code:: bash
kubectl -n mailu-mailserver delete po/mailu-imap-....
Wait for the pod to recreate and you're online!
Happy mailing!
.. _here: https://github.com/hacor/Mailu/blob/master/core/postfix/conf/main.cf#L35
.. _cert-manager: https://github.com/jetstack/cert-manager
.. _docs: https://cert-manager.readthedocs.io/en/latest/getting-started/2-installing.html
Imap login fix
~~~~~~~~~~~~~~
If it seems you're not able to login using IMAP on your Mailu accounts, check the logs of the imap container to see whether it's a permissions problem on the database.
This problem can be easily fixed by running following commands:
.. code:: bash
kubectl -n mailu-mailserver exec -it mailu-imap-... /bin/sh
chmod 777 /data/main.db

0
docs/kubernetes/1.6/mailu/pvc.yaml → docs/kubernetes/mailu/pvc.yaml
View File

0
docs/kubernetes/1.6/mailu/rbac.yaml → docs/kubernetes/mailu/rbac.yaml
View File

0
docs/kubernetes/1.6/mailu/redis.yaml → docs/kubernetes/mailu/redis.yaml
View File

30
docs/kubernetes/mailu/security-ingress.yaml Normal file
View File

@@ -0,0 +1,30 @@
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: mailu-antispam-ingress
namespace: mailu-mailserver
annotations:
kubernetes.io/tls-acme: "true"
certmanager.k8s.io/cluster-issuer: letsencrypt-stage
ingress.kubernetes.io/configuration-snippet: |
rewrite ^/admin/antispam/(.*) /$1 break;
auth_request /internal/auth/admin;
proxy_set_header X-Real-IP "";
proxy_set_header X-Forwarded-For "";
labels:
app: mailu
role: mail
tier: frontend
spec:
tls:
- hosts:
- "mail.example.com"
secretName: letsencrypt-certs-all # If unsure how to generate these, check out https://github.com/ployst/docker-letsencrypt
rules:
- host: "mail.example.com"
http:
paths:
- path: "/admin/antispam"
backend:
serviceName: antispam
servicePort: 11334

6
docs/kubernetes/1.6/mailu/security.yaml → docs/kubernetes/mailu/security.yaml
View File

@@ -31,6 +31,9 @@ spec:
- name: antispam
containerPort: 11332
protocol: TCP
- name: antispam-http
containerPort: 11334
protocol: TCP
volumeMounts:
- name: filter
subPath: filter
@@ -87,6 +90,9 @@ spec:
- name: antispam
port: 11332
protocol: TCP
- name: antispam-http
protocol: TCP
port: 11334
---

6
docs/kubernetes/1.6/mailu/smtp.yaml → docs/kubernetes/mailu/smtp.yaml
View File

@@ -21,10 +21,10 @@ spec:
name: mailu-config
resources:
requests:
memory: 500Mi
cpu: 200m
memory: 2Gi
cpu: 500m
limits:
memory: 1Gi
memory: 2Gi
cpu: 500m
volumeMounts:
- mountPath: /data

46
docs/kubernetes/mailu/webdav-ingress.yaml Normal file
View File

@@ -0,0 +1,46 @@
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: mailu-webdav-ingress
namespace: mailu-mailserver
annotations:
kubernetes.io/tls-acme: "true"
nginx.ingress.kubernetes.io/proxy-body-size: "0"
certmanager.k8s.io/cluster-issuer: letsencrypt-stage
#ingress.kubernetes.io/auth-url: http://admin.mailu-mailserver.svc.cluster.local/internal/auth/basic
ingress.kubernetes.io/configuration-snippet: |
rewrite ^/webdav/(.*) /$1 break;
auth_request /internal/auth/basic;
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
auth_request_set $user $upstream_http_x_user;
proxy_set_header X-Remote-User $user;
proxy_set_header X-Script-Name /webdav;
ingress.kubernetes.io/server-snippet: |
location /internal {
internal;
proxy_set_header Authorization $http_authorization;
proxy_pass_header Authorization;
proxy_pass http://admin.mailu-mailserver.svc.cluster.local;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
}
labels:
app: mailu
role: mail
tier: frontend
spec:
tls:
- hosts:
- "mail.example.com"
secretName: letsencrypt-certs-all # If unsure how to generate these, check out https://github.com/ployst/docker-letsencrypt
rules:
- host: "mail.example.com"
http:
paths:
- path: "/webdav"
backend:
serviceName: webdav
servicePort: 5232

0
docs/kubernetes/1.6/mailu/webdav.yaml → docs/kubernetes/mailu/webdav.yaml
View File

31
docs/kubernetes/mailu/webmail-ingress.yaml Normal file
View File

@@ -0,0 +1,31 @@
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: mailu-webmail-ingress
namespace: mailu-mailserver
annotations:
kubernetes.io/tls-acme: "true"
nginx.ingress.kubernetes.io/proxy-body-size: "0"
certmanager.k8s.io/cluster-issuer: letsencrypt-stage
nginx.ingress.kubernetes.io/configuration-snippet: |
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $proxy_x_forwarded_proto;
labels:
app: mailu
role: mail
tier: backend
spec:
tls:
- hosts:
- "webmail.example.com"
secretName: letsencrypt-webmail # If unsure how to generate these, check out https://github.com/ployst/docker-letsencrypt
rules:
- host: "webmail.example.com"
http:
paths:
- path: "/"
backend:
serviceName: webmail
servicePort: 80

2
docs/kubernetes/1.6/mailu/webmail.yaml → docs/kubernetes/mailu/webmail.yaml
View File

@@ -15,7 +15,7 @@ spec:
spec:
containers:
- name: roundcube
image: mailu/roundcube:1.5
image: mailu/roundcube:master
imagePullPolicy: Always
envFrom:
- configMapRef:

0
docs/kubernetes/1.6/nginx/default-http-backend.yaml → docs/kubernetes/nginx/default-http-backend.yaml
View File

26
docs/kubernetes/1.6/nginx/nginx-ingress.yaml → docs/kubernetes/nginx/nginx-ingress.yaml
View File

@@ -2,15 +2,15 @@ apiVersion: v1
kind: Service
metadata:
# keep it under 24 chars
name: appsynth-lb
name: ingress-lb
namespace: kube-ingress
labels:
k8s-app: appsynth-lb
k8s-app: ingress-lb
component: ingress-controller
spec:
type: ClusterIP
selector:
k8s-app: appsynth-lb
k8s-app: ingress-lb
component: ingress-controller
ports:
- name: http
@@ -35,13 +35,6 @@ metadata:
name: tcp-services
namespace: kube-ingress
data:
25: "mailu-mailserver/front:25"
110: "mailu-mailserver/front:110"
465: "mailu-mailserver/front:465"
587: "mailu-mailserver/front:587"
143: "mailu-mailserver/front:143"
993: "mailu-mailserver/front:993"
995: "mailu-mailserver/front:995"
---
apiVersion: v1
@@ -61,7 +54,7 @@ metadata:
prometheus.io/port: "10254"
prometheus.io/scrape: "true"
labels:
k8s-app: appsynth-lb
k8s-app: ingress-lb
component: ingress-controller
type: nginx
spec:
@@ -71,13 +64,13 @@ spec:
type: RollingUpdate
selector:
matchLabels:
k8s-app: appsynth-lb
k8s-app: ingress-lb
component: ingress-controller
type: nginx
template:
metadata:
labels:
k8s-app: appsynth-lb
k8s-app: ingress-lb
component: ingress-controller
type: nginx
spec:
@@ -94,14 +87,11 @@ spec:
image: quay.io/kubernetes-ingress-controller/nginx-ingress-controller:0.16.2
args:
- /nginx-ingress-controller
- --configmap=$(POD_NAMESPACE)/tectonic-custom-error
- --default-backend-service=$(POD_NAMESPACE)/default-http-backend
#- --default-ssl-certificate=tectonic-system/tectonic-ingress-tls-secret
- --tcp-services-configmap=$(POD_NAMESPACE)/tcp-services
- --udp-services-configmap=$(POD_NAMESPACE)/udp-services
- --annotations-prefix=ingress.kubernetes.io
- --enable-ssl-passthrough
- --ingress-class=tectonic
# use downward API
env:
- name: POD_NAME
@@ -115,10 +105,8 @@ spec:
ports:
- name: http
containerPort: 80
hostPort: 80
- name: https
containerPort: 443
hostPort: 443
readinessProbe:
httpGet:
path: /healthz
@@ -134,6 +122,6 @@ spec:
hostNetwork: true
nodeSelector:
node-role.kubernetes.io/node: ""
dnsPolicy: ClusterFirst
dnsPolicy: ClusterFirstWithHostNet
restartPolicy: Always
terminationGracePeriodSeconds: 60

0
docs/kubernetes/1.6/nginx/rbac.yaml → docs/kubernetes/nginx/rbac.yaml
View File

26
docs/kubernetes/stable/index.rst
View File

@@ -1,26 +0,0 @@
Kubernetes setup
================
Please note that Kubernetes setup is not yet well supported or documented, all
tests currently run on Docker Compose. The configuration has not yet been updated
to work properly with ngin authentication proxy.
Prepare the environment
-----------------------
The resource configurations in this folder assume that you have `Kubernetes Ingress`_
set up for your cluster. If you are not using the `NGINX Ingress Controller for Kubernetes`_,
please ensure that the configuration specified in the file matches your set up.
.. _`Kubernetes Ingress`: https://kubernetes.io/docs/concepts/services-networking/ingress/
.. _`NGINX Ingress Controller for Kubernetes`: https://github.com/kubernetes/ingress/tree/master/controllers/nginx
Setup the Kubernetes service
----------------------------
Using the resource configurations is simple:
1. ``kubectl apply -f kubernetes-nginx-ingress-controller.yaml`` to configure an ingress controller with the proper settings. (If you have one set up already you may need to port the configuration to your own ingress).
2. ``kubectl apply -f kubernetes-mailu.yaml`` to create the resources required to run Mailu.
Based on the configuration, your Mailu instance should be available at ``mail.<hostname>.tld/admin`` (note that visiting just ``mail.<hostname>.tld`` will likely result in a 404 error).

419
docs/kubernetes/stable/kubernetes-mailu.yaml
View File

@@ -1,419 +0,0 @@
---
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: mailu-admin-ing
labels:
app: mailu
role: mail
tier: backend
spec:
tls:
- hosts:
- "mail.example.com"
secretName: letsencrypt-certs-all # If unsure how to generate these, check out https://github.com/ployst/docker-letsencrypt
rules:
- host: "mail.example.com"
http:
paths:
- path: "/admin"
backend:
serviceName: mailu-admin
servicePort: 80
---
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
name: mailu-redis
spec:
replicas: 1
template:
metadata:
labels:
app: mailu-redis
role: mail
tier: backend
spec:
containers:
- name: redis
image: redis:4.0-alpine
imagePullPolicy: Always
volumeMounts:
- mountPath: /data
name: redisdata
ports:
- containerPort: 6379
name: redis
protocol: TCP
volumes:
- name: redisdata
hostPath:
path: /var/data/mailu/redisdata
---
apiVersion: v1
kind: Service
metadata:
name: redis
labels:
app: mailu-redis
role: mail
tier: backend
spec:
selector:
app: mailu
role: mail
tier: backend
ports:
- name: redis
port: 6379
protocol: TCP
---
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
name: mailu-imap
spec:
replicas: 1
template:
metadata:
labels:
app: mailu-imap
role: mail
tier: backend
spec:
containers:
- name: imap
image: mailu/dovecot:stable
imagePullPolicy: Always
env:
- name : DOMAIN
value : example.com
- name : HOSTNAME
value : mail.example.com
- name : POSTMASTER
value : admin
volumeMounts:
- mountPath: /data
name: maildata
- mountPath: /mail
name: mailstate
- mountPath: /overrides
name: overrides
- mountPath: /certs
name: certs
readOnly: true
ports:
- containerPort: 2102
- containerPort: 2525
- containerPort: 143
- containerPort: 993
- containerPort: 4190
volumes:
- name: maildata
hostPath:
path: /var/data/mailu/maildata
- name: mailstate
hostPath:
path: /var/data/mailu/mailstate
- name: overrides
hostPath:
path: /var/data/mailu/overrides
- name: certs
secret:
items:
- key: tls.crt
path: cert.pem
- key: tls.key
path: key.pem
secretName: letsencrypt-certs-all
---
apiVersion: v1
kind: Service
metadata:
name: imap
labels:
app: mailu
role: mail
tier: backend
spec:
selector:
app: mailu-imap
role: mail
tier: backend
ports:
ports:
- name: imap-auth
port: 2102
protocol: TCP
- name: imap-transport
port: 2525
protocol: TCP
- name: imap-default
port: 143
protocol: TCP
- name: imap-ssl
port: 993
protocol: TCP
- name: sieve
port: 4190
protocol: TCP
---
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
name: mailu-smtp
spec:
replicas: 1
template:
metadata:
labels:
app: mailu-smtp
role: mail
tier: backend
spec:
containers:
- name: smtp
image: mailu/postfix:stable
imagePullPolicy: Always
env:
- name : DOMAIN
value : example.com
- name : HOSTNAME
value : mail.example.com
- name : MESSAGE_SIZE_LIMIT
value : "50000000"
- name : RELAYHOST
value : ""
volumeMounts:
- mountPath: /data
name: maildata
- mountPath: /overrides
name: overrides
- mountPath: /certs
name: certs
readOnly: true
ports:
- name: smtp
containerPort: 25
protocol: TCP
- name: smtp-ssl
containerPort: 465
protocol: TCP
- name: smtp-starttls
containerPort: 587
protocol: TCP
volumes:
- name: maildata
hostPath:
path: /var/data/mailu/maildata
- name: overrides
hostPath:
path: /var/data/mailu/overrides
- name: certs
secret:
items:
- key: tls.crt
path: cert.pem
- key: tls.key
path: key.pem
secretName: letsencrypt-certs-all
---
apiVersion: v1
kind: Service
metadata:
name: smtp
labels:
app: mailu
role: mail
tier: backend
spec:
selector:
app: mailu-smtp
role: mail
tier: backend
ports:
- name: smtp
port: 25
protocol: TCP
- name: smtp-ssl
port: 465
protocol: TCP
- name: smtp-starttls
port: 587
protocol: TCP
---
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
name: mailu-security
spec:
replicas: 1
template:
metadata:
labels:
app: mailu-security
role: mail
tier: backend
spec:
containers:
- name: antispam
image: mailu/rspamd:stable
imagePullPolicy: Always
ports:
- name: antispam
containerPort: 11333
protocol: TCP
volumeMounts:
- name: filter
mountPath: /var/lib/rspamd
- name: antivirus
image: mailu/clamav:stable
imagePullPolicy: Always
ports:
- name: antivirus
containerPort: 3310
protocol: TCP
volumeMounts:
- name: filter
mountPath: /data
volumes:
- name: filter
hostPath:
path: /var/data/mailu/filter
---
apiVersion: v1
kind: Service
metadata:
name: antispam
labels:
app: mailu-antispam
role: mail
tier: backend
spec:
selector:
app: mailu-security
role: mail
tier: backend
ports:
- name: antispam
port: 11333
protocol: TCP
---
apiVersion: v1
kind: Service
metadata:
name: antivirus
labels:
app: mailu-antivirus
role: mail
tier: backend
spec:
selector:
app: mailu-security
role: mail
tier: backend
ports:
- name: antivirus
port: 3310
protocol: TCP
---
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
name: mailu-admin
spec:
replicas: 1
template:
metadata:
labels:
app: mailu-admin
role: mail
tier: backend
spec:
containers:
- name: admin
image: mailu/admin:stable
imagePullPolicy: Always
env:
- name : DOMAIN
value : example.com
- name : HOSTNAME
value : mail.example.com
- name : POSTMASTER
value : core
- name : SECRET_KEY
value : pleasereplacethiswithabetterkey
- name : DEBUG
value : "True"
volumeMounts:
- name: maildata
mountPath: /data
- name: dkim
mountPath: /dkim
- name: certs
mountPath: /certs
readOnly: true
# - name: docker
# mountPath: /var/run/docker.sock
# readOnly: true
ports:
- name: http
containerPort: 80
protocol: TCP
volumes:
- name: maildata
hostPath:
path: /var/data/mailu/maildata
- name: dkim
hostPath:
path: /var/data/mailu/dkim
- name: certs
secret:
items:
- key: tls.crt
path: cert.pem
- key: tls.key
path: key.pem
secretName: letsencrypt-certs-all
# - name: docker
# hostPath:
# path: /var/run/docker.sock
---
apiVersion: v1
kind: Service
metadata:
name: mailu-admin
labels:
app: mailu-admin
role: mail
tier: backend
spec:
selector:
app: mailu-admin
role: mail
tier: backend
ports:
- name: http
port: 80
protocol: TCP

84
docs/kubernetes/stable/kubernetes-nginx-ingress-controller.yaml
View File

@@ -1,84 +0,0 @@
---
kind: ConfigMap
apiVersion: v1
metadata:
name: nginx-configuration
namespace: ingress-nginx
labels:
app: ingress-nginx
---
kind: ConfigMap
apiVersion: v1
metadata:
name: udp-services
namespace: ingress-nginx
---
kind: ConfigMap
apiVersion: v1
metadata:
name: tcp-services
namespace: ingress-nginx
data:
25: "mailu/smtp:25"
465: "mailu/smtp:465"
587: "mailu/smtp:587"
143: "mailu/imap:143"
993: "mailu/imap:993"
---
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
name: nginx-ingress-controller
namespace: kube-system
labels:
k8s-app: nginx-ingress-controller
spec:
replicas: 1
template:
metadata:
labels:
k8s-app: nginx-ingress-controller
annotations:
prometheus.io/port: '10254'
prometheus.io/scrape: 'true'
spec:
# hostNetwork makes it possible to use ipv6 and to preserve the source IP correctly regardless of docker configuration
# however, it is not a hard dependency of the nginx-ingress-controller itself and it may cause issues if port 10254 already is taken on the host
# that said, since hostPort is broken on CNI (https://github.com/kubernetes/kubernetes/issues/31307) we have to use hostNetwork where CNI is used
# like with kubeadm
# hostNetwork: true
terminationGracePeriodSeconds: 60
containers:
- image: gcr.io/google_containers/nginx-ingress-controller:0.11.0
name: nginx-ingress-controller
args:
- /nginx-ingress-controller
- --default-backend-service=$(POD_NAMESPACE)/default-http-backend
- --configmap=$(POD_NAMESPACE)/nginx-configuration
- --tcp-services-configmap=$(POD_NAMESPACE)/tcp-services
- --udp-services-configmap=$(POD_NAMESPACE)/udp-services
- --annotations-prefix=nginx.ingress.kubernetes.io
readinessProbe:
httpGet:
path: /healthz
port: 10254
scheme: HTTP
livenessProbe:
httpGet:
path: /healthz
port: 10254
scheme: HTTP
initialDelaySeconds: 10
timeoutSeconds: 1
env:
- name: POD_NAME
valueFrom:
fieldRef:
fieldPath: metadata.name
- name: POD_NAMESPACE
valueFrom:
fieldRef:
fieldPath: metadata.namespace

27
docs/maintain.rst
View File

@@ -28,6 +28,33 @@ Logs are managed by Docker directly. You can easily read your logs using:
Docker is able to forward logs to multiple log engines. Read the following documentation for details: https://docs.docker.com/engine/admin/logging/overview/.
.. _external_certs:
Managing of external Let's encrypt certificates
-----------------------------------------------
When you are not using the embedded ``letsencrypt`` option from Mailu,
you cannot make use of it's symlink functionality in the ``letsencrypt/live`` directory.
You should take care that after every renewal new certificates are copied to ``/mailu/certs`` and
the *nginx* process in the ``front`` container is reloaded.
In the case of *certbot* you could write a script to be executed as `deploy hook`_. Example:
.. code-block:: bash
#!/bin/sh
cp /etc/letsencrypt/live/domain.com/privkey.pem /mailu/certs/key.pem || exit 1
cp /etc/letsencrypt/live/domain.com/fullchain.pem /mailu/certs/cert.pem || exit 1
docker exec mailu_front_1 nginx -s reload
And the certbot command you will use in crontab would look something like:
.. code-block:: bash
52 0,12 * * * root /usr/bin/certbot renew --deploy-hook /path/to/script.sh
.. _`deploy hook`: https://certbot.eff.org/docs/using.html#renewing-certificates
Migrating an instance
---------------------

252
docs/swarm/master/README.md Normal file
View File

@@ -0,0 +1,252 @@
# Install Mailu on a docker swarm
## Prequisites
### Swarm
In order to deploy Mailu on a swarm, you will first need to initialize the swarm:
The main command will be:
```bash
docker swarm init --advertise-addr <IP_ADDR>
```
See https://docs.docker.com/engine/swarm/swarm-tutorial/create-swarm/
If you want to add other managers or workers, please use:
```bash
docker swarm join --token xxxxx
```
See https://docs.docker.com/engine/swarm/join-nodes/
You have now a working swarm, and you can check its status with:
```bash
core@coreos-01 ~/git/Mailu/docs/swarm/1.5 $ docker node ls
ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS ENGINE VERSION
xhgeekkrlttpmtgmapt5hyxrb black-pearl Ready Active 18.06.0-ce
sczlqjgfhehsfdjhfhhph1nvb * coreos-01 Ready Active Leader 18.03.1-ce
mzrm9nbdggsfz4sgq6dhs5i6n flying-dutchman Ready Active 18.06.0-ce
```
### Volume definition
For data persistance (the Mailu services might be launched/relaunched on any of the swarm nodes), we need to have Mailu data stored in a manner accessible by every manager or worker in the swarm.
Hereafter we will assume that "Mailu Data" is available on every node at "$ROOT/certs:/certs" (GlusterFS and nfs shares have been successfully used).
On this example, we are using:
- the mesh routing mode (default mode). With this mode, each service is given a virtual IP adress and docker manages the routing between this virtual IP and the container(s) providing this service.
- the default ingress mode.
### Allow authentification with the mesh routing
In order to allow every (front & webmail) container to access the other services, we will use the variable POD_ADDRESS_RANGE.
Let's create the mailu_default network:
```bash
core@coreos-01 ~ $ docker network create -d overlay --attachable mailu_default
core@coreos-01 ~ $ docker network inspect mailu_default | grep Subnet
"Subnet": "10.0.1.0/24",
```
In the docker-compose.yml file, we will then use POD_ADDRESS_RANGE = 10.0.1.0/24
In fact, imap & smtp logs doesn't show the IPs from the front(s) container(s), but the IP of "mailu_default-endpoint". So it is sufficient to set POD_ADDRESS_RANGE to this specific ip (which can be found by inspecting mailu_default network). The issue is that this endpoint is created while the stack is created, I did'nt figure a way to determine this IP before the stack creation...
### Limitation with the ingress mode
With the default ingress mode, the front(s) container(s) will see origin IP(s) all being 10.255.0.x (which is the ingress-endpoint, can be found by inspecting the ingress network)
This issue is known and discussed here:
https://github.com/moby/moby/issues/25526
A workaround (using network host mode and global deployment) is discussed here:
https://github.com/moby/moby/issues/25526#issuecomment-336363408
### Don't create an open relay !
As a side effect of this ingress mode "feature", make sure that the ingress subnet is not in your RELAYHOST, otherwise you would create an smtp open relay :-(
## Scalability
- smtp and imap are scalable
- front and webmail are scalable (pending POD_ADDRESS_RANGE is used), although the let's encrypt magic might not like it (race condidtion ? or risk to be banned by let's encrypt server if too many front containers attemps to renew the certs at the same time)
- redis, antispam, antivirus, fetchmail, admin, webdav have not been tested (hence replicas=1 in the following docker-compose.yml file)
## Variable substitution and docker-compose.yml
The docker stack deploy command doesn't support variable substitution in the .yml file itself.
As a consequence, we cannot simply use ``` docker stack deploy -c docker.compose.yml mailu ```
Instead, we will use the following work-around:
``` echo "$(docker-compose -f /mnt/docker/apps/mailu/docker-compose.yml config 2>/dev/null)" | docker stack deploy -c- mailu ```
We need also to:
- add a deploy section for every service
- modify the way the ports are defined for the front service
- add the POD_ADDRESS_RANGE definition for imap, smtp and antispam services
## Docker compose
An example of docker-compose-stack.yml file is available here:
```yaml
version: '3.2'
services:
front:
image: mailu/nginx:$VERSION
restart: always
env_file: .env
ports:
- target: 80
published: 80
- target: 443
published: 443
- target: 110
published: 110
- target: 143
published: 143
- target: 993
published: 993
- target: 995
published: 995
- target: 25
published: 25
- target: 465
published: 465
- target: 587
published: 587
volumes:
- "$ROOT/certs:/certs"
deploy:
replicas: 2
redis:
image: redis:alpine
restart: always
volumes:
- "$ROOT/redis:/data"
deploy:
replicas: 1
imap:
image: mailu/dovecot:$VERSION
restart: always
env_file: .env
environment:
- POD_ADDRESS_RANGE=10.0.1.0/24
volumes:
- "$ROOT/mail:/mail"
- "$ROOT/overrides:/overrides"
depends_on:
- front
deploy:
replicas: 2
smtp:
image: mailu/postfix:$VERSION
restart: always
env_file: .env
environment:
- POD_ADDRESS_RANGE=10.0.1.0/24
volumes:
- "$ROOT/overrides:/overrides"
depends_on:
- front
deploy:
replicas: 2
antispam:
image: mailu/rspamd:$VERSION
restart: always
env_file: .env
environment:
- POD_ADDRESS_RANGE=10.0.1.0/24
volumes:
- "$ROOT/filter:/var/lib/rspamd"
- "$ROOT/dkim:/dkim"
- "$ROOT/overrides/rspamd:/etc/rspamd/override.d"
depends_on:
- front
deploy:
replicas: 1
antivirus:
image: mailu/none:$VERSION
restart: always
env_file: .env
volumes:
- "$ROOT/filter:/data"
deploy:
replicas: 1
webdav:
image: mailu/none:$VERSION
restart: always
env_file: .env
volumes:
- "$ROOT/dav:/data"
deploy:
replicas: 1
admin:
image: mailu/admin:$VERSION
restart: always
env_file: .env
volumes:
- "$ROOT/data:/data"
- "$ROOT/dkim:/dkim"
- /var/run/docker.sock:/var/run/docker.sock:ro
depends_on:
- redis
deploy:
replicas: 1
webmail:
image: mailu/roundcube:$VERSION
restart: always
env_file: .env
volumes:
- "$ROOT/webmail:/data"
depends_on:
- imap
deploy:
replicas: 2
fetchmail:
image: mailu/fetchmail:$VERSION
restart: always
env_file: .env
volumes:
deploy:
replicas: 1
networks:
default:
external:
name: mailu_default
```
## Deploy Mailu on the docker swarm
Run the following command:
```bash
echo "$(docker-compose -f /mnt/docker/apps/mailu/docker-compose.yml config 2>/dev/null)" | docker stack deploy -c- mailu
```
See how the services are being deployed:
```bash
core@coreos-01 ~ $ docker service ls
ID NAME MODE REPLICAS IMAGE PORTS
ywnsetmtkb1l mailu_antivirus replicated 1/1 mailu/none:master
pqokiaz0q128 mailu_fetchmail replicated 1/1 mailu/fetchmail:master
```
check a specific service:
```bash
core@coreos-01 ~ $ docker service ps mailu_fetchmail
ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS
tbu8ppgsdffj mailu_fetchmail.1 mailu/fetchmail:master coreos-01 Running Running 11 days ago
```
You might also have a look on the logs:
```bash
core@coreos-01 ~ $ docker service logs -f mailu_fetchmail
```
## Remove the stack
Run the follwoing command:
```bash
core@coreos-01 ~ $ docker stack rm mailu
```

357
docs/swarm/master/README_nfs_example.md Normal file
View File

@@ -0,0 +1,357 @@
# Install Mailu on a docker swarm
## Prequisites
### Swarm
In order to deploy Mailu on a swarm, you will first need to initialize the swarm:
The main command will be:
```bash
docker swarm init --advertise-addr <IP_ADDR>
```
See https://docs.docker.com/engine/swarm/swarm-tutorial/create-swarm/
If you want to add other managers or workers, please use:
```bash
docker swarm join --token xxxxx
```
See https://docs.docker.com/engine/swarm/join-nodes/
You have now a working swarm, and you can check its status with:
```bash
core@coreos-01 ~/git/Mailu/docs/swarm/1.5 $ docker node ls
ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS ENGINE VERSION
xhgeekkrlttpmtgmapt5hyxrb black-pearl Ready Active 18.06.0-ce
sczlqjgfhehsfdjhfhhph1nvb * coreos-01 Ready Active Leader 18.03.1-ce
mzrm9nbdggsfz4sgq6dhs5i6n flying-dutchman Ready Active 18.06.0-ce
```
### Volume definition
For data persistance (the Mailu services might be launched/relaunched on any of the swarm nodes), we need to have Mailu data stored in a manner accessible by every manager or worker in the swarm.
Hereafter we will use a NFS share:
```bash
core@coreos-01 ~ $ showmount -e 192.168.0.30
Export list for 192.168.0.30:
/mnt/Pool1/pv 192.168.0.0
```
on the nfs server, I am using the following /etc/exports
```bash
$more /etc/exports
/mnt/Pool1/pv -alldirs -mapall=root -network 192.168.0.0 -mask 255.255.255.0
```
on the nfs server, I created the Mailu directory (in fact I copied a working Mailu set-up)
```bash
$mkdir /mnt/Pool1/pv/mailu
```
On your manager node, mount the nfs share to check that the share is available:
```bash
core@coreos-01 ~ $ sudo mount -t nfs 192.168.0.30:/mnt/Pool1/pv/mailu /mnt/local/
```
If this is ok, you can umount it:
```bash
core@coreos-01 ~ $ sudo umount /mnt/local/
```
## Networking mode
On this example, we are using:
- the mesh routing mode (default mode). With this mode, each service is given a virtual IP adress and docker manages the routing between this virtual IP and the container(s) providing this service.
- the default ingress mode.
### Allow authentification with the mesh routing
In order to allow every (front & webmail) container to access the other services, we will use the variable POD_ADDRESS_RANGE.
Let's create the mailu_default network:
```bash
core@coreos-01 ~ $ docker network create -d overlay --attachable mailu_default
core@coreos-01 ~ $ docker network inspect mailu_default | grep Subnet
"Subnet": "10.0.1.0/24",
```
In the docker-compose.yml file, we will then use POD_ADDRESS_RANGE = 10.0.1.0/24
In fact, imap & smtp logs doesn't show the IPs from the front(s) container(s), but the IP of "mailu_default-endpoint". So it is sufficient to set POD_ADDRESS_RANGE to this specific ip (which can be found by inspecting mailu_default network). The issue is that this endpoint is created while the stack is created, I did'nt figure a way to determine this IP before the stack creation...
### Limitation with the ingress mode
With the default ingress mode, the front(s) container(s) will see origin IP(s) all being 10.255.0.x (which is the ingress-endpoint, can be found by inspecting the ingress network)
This issue is known and discussed here:
https://github.com/moby/moby/issues/25526
A workaround (using network host mode and global deployment) is discussed here:
https://github.com/moby/moby/issues/25526#issuecomment-336363408
### Don't create an open relay !
As a side effect of this ingress mode "feature", make sure that the ingress subnet is not in your RELAYHOST, otherwise you would create an smtp open relay :-(
## Scalability
- smtp and imap are scalable
- front and webmail are scalable (pending POD_ADDRESS_RANGE is used), although the let's encrypt magic might not like it (race condidtion ? or risk to be banned by let's encrypt server if too many front containers attemps to renew the certs at the same time)
- redis, antispam, antivirus, fetchmail, admin, webdav have not been tested (hence replicas=1 in the following docker-compose.yml file)
## Variable substitution and docker-compose.yml
The docker stack deploy command doesn't support variable substitution in the .yml file itself. As a consequence, we need to use the following work-around:
``` echo "$(docker-compose -f /mnt/docker/apps/mailu/docker-compose.yml config 2>/dev/null)" | docker stack deploy -c- mailu ```
We need also to:
- change the way we define the volumes (nfs share in our case)
- add a deploy section for every service
- the way the ports are defined for the front service
## Docker compose
An example of docker-compose-stack.yml file is available here:
```yaml
version: '3.2'
services:
front:
image: mailu/nginx:$VERSION
restart: always
env_file: .env
ports:
- target: 80
published: 80
- target: 443
published: 443
- target: 110
published: 110
- target: 143
published: 143
- target: 993
published: 993
- target: 995
published: 995
- target: 25
published: 25
- target: 465
published: 465
- target: 587
published: 587
volumes:
# - "$ROOT/certs:/certs"
- type: volume
source: mailu_certs
target: /certs
deploy:
replicas: 2
redis:
image: redis:alpine
restart: always
volumes:
# - "$ROOT/redis:/data"
- type: volume
source: mailu_redis
target: /data
deploy:
replicas: 1
imap:
image: mailu/dovecot:$VERSION
restart: always
env_file: .env
environment:
- POD_ADDRESS_RANGE=10.0.1.0/24
volumes:
# - "$ROOT/mail:/mail"
- type: volume
source: mailu_mail
target: /mail
# - "$ROOT/overrides:/overrides"
- type: volume
source: mailu_overrides
target: /overrides
depends_on:
- front
deploy:
replicas: 2
smtp:
image: mailu/postfix:$VERSION
restart: always
env_file: .env
environment:
- POD_ADDRESS_RANGE=10.0.1.0/24
volumes:
# - "$ROOT/overrides:/overrides"
- type: volume
source: mailu_overrides
target: /overrides
depends_on:
- front
deploy:
replicas: 2
antispam:
image: mailu/rspamd:$VERSION
restart: always
env_file: .env
environment:
- POD_ADDRESS_RANGE=10.0.1.0/24
depends_on:
- front
volumes:
# - "$ROOT/filter:/var/lib/rspamd"
- type: volume
source: mailu_filter
target: /var/lib/rspamd
# - "$ROOT/dkim:/dkim"
- type: volume
source: mailu_dkim
target: /dkim
# - "$ROOT/overrides/rspamd:/etc/rspamd/override.d"
- type: volume
source: mailu_overrides_rspamd
target: /etc/rspamd/override.d
deploy:
replicas: 1
antivirus:
image: mailu/none:$VERSION
restart: always
env_file: .env
volumes:
# - "$ROOT/filter:/data"
- type: volume
source: mailu_filter
target: /data
deploy:
replicas: 1
webdav:
image: mailu/none:$VERSION
restart: always
env_file: .env
volumes:
# - "$ROOT/dav:/data"
- type: volume
source: mailu_dav
target: /data
deploy:
replicas: 1
admin:
image: mailu/admin:$VERSION
restart: always
env_file: .env
volumes:
# - "$ROOT/data:/data"
- type: volume
source: mailu_data
target: /data
# - "$ROOT/dkim:/dkim"
- type: volume
source: mailu_dkim
target: /dkim
- /var/run/docker.sock:/var/run/docker.sock:ro
depends_on:
- redis
deploy:
replicas: 1
webmail:
image: mailu/roundcube:$VERSION
restart: always
env_file: .env
volumes:
# - "$ROOT/webmail:/data"
- type: volume
source: mailu_data
target: /data
depends_on:
- imap
deploy:
replicas: 2
fetchmail:
image: mailu/fetchmail:$VERSION
restart: always
env_file: .env
volumes:
deploy:
replicas: 1
networks:
default:
external:
name: mailu_default
volumes:
mailu_filter:
driver_opts:
type: "nfs"
o: "addr=192.168.0.30,soft,rw"
device: ":/mnt/Pool1/pv/mailu/filter"
mailu_dkim:
driver_opts:
type: "nfs"
o: "addr=192.168.0.30,soft,rw"
device: ":/mnt/Pool1/pv/mailu/dkim"
mailu_overrides_rspamd:
driver_opts:
type: "nfs"
o: "addr=192.168.0.30,soft,rw"
device: ":/mnt/Pool1/pv/mailu/overrides/rspamd"
mailu_data:
driver_opts:
type: "nfs"
o: "addr=192.168.0.30,soft,rw"
device: ":/mnt/Pool1/pv/mailu/data"
mailu_mail:
driver_opts:
type: "nfs"
o: "addr=192.168.0.30,soft,rw"
device: ":/mnt/Pool1/pv/mailu/mail"
mailu_overrides:
driver_opts:
type: "nfs"
o: "addr=192.168.0.30,soft,rw"
device: ":/mnt/Pool1/pv/mailu/overrides"
mailu_dav:
driver_opts:
type: "nfs"
o: "addr=192.168.0.30,soft,rw"
device: ":/mnt/Pool1/pv/mailu/dav"
mailu_certs:
driver_opts:
type: "nfs"
o: "addr=192.168.0.30,soft,rw"
device: ":/mnt/Pool1/pv/mailu/certs"
mailu_redis:
driver_opts:
type: "nfs"
o: "addr=192.168.0.30,soft,rw"
device: ":/mnt/Pool1/pv/mailu/redis"
```
## Deploy Mailu on the docker swarm
Run the following command:
```bash
echo "$(docker-compose -f /mnt/docker/apps/mailu/docker-compose.yml config 2>/dev/null)" | docker stack deploy -c- mailu
```
See how the services are being deployed:
```bash
core@coreos-01 ~ $ docker service ls
ID NAME MODE REPLICAS IMAGE PORTS
ywnsetmtkb1l mailu_antivirus replicated 1/1 mailu/none:master
pqokiaz0q128 mailu_fetchmail replicated 1/1 mailu/fetchmail:master
```
check a specific service:
```bash
core@coreos-01 ~ $ docker service ps mailu_fetchmail
ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS
tbu8ppgsdffj mailu_fetchmail.1 mailu/fetchmail:master coreos-01 Running Running 11 days ago
```
## Remove the stack
Run the follwoing command:
```bash
core@coreos-01 ~ $ docker stack rm mailu
```