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

Fix the rst syntax for most documentation

Browse Source
master
kaiyou 7 years ago
parent dc2f1280ed
commit fcf9515bff
13 changed files with 217 additions and 213 deletions
Show Stats Download Patch File Download Diff File

102
docs/cli.md
Unescape Escape View File

@ -1,102 +0,0 @@
Mailu command line
==================
Managing users and aliases can be done from CLI using commands:
* alias
* alias_delete
* user
* user_import
* user_delete
* config_update
alias
-----
```
docker-compose run --rm admin python manage.py alias foo example.net "mail1@example.com,mail2@example.com"
```
alias_delete
------------
```
docker-compose run --rm admin python manage.py alias_delete foo@example.net
```
user
----
```
docker-compose run --rm admin python manage.py user --hash_scheme='SHA512-CRYPT' myuser example.net 'password123'
```
user_import
-----------
primary difference with simple `user` command is that password is being imported as a hash - very useful when migrating users from other systems where only hash is known.
```
docker-compose run --rm admin python manage.py user --hash_scheme='SHA512-CRYPT' myuser example.net '$6$51ebe0cb9f1dab48effa2a0ad8660cb489b445936b9ffd812a0b8f46bca66dd549fea530ce'
```
user_delete
------------
```
docker-compose run --rm admin python manage.py user_delete foo@example.net
```
config_update
-------------
This command sole purpose is for importing users/aliases in bulk and synchronizing DB entries with external YAML template:
```
cat mail-config.yml | docker-compose run --rm admin python manage.py config_update --delete_objects
```
where mail-config.yml looks like:
```
---
users:
- localpart: foo
domain: example.com
password_hash: klkjhumnzxcjkajahsdqweqqwr
hash_scheme: MD5-CRYPT
aliases:
- localpart: alias1
domain: example.com
destination: "user1@example.com,user2@example.com"
```
without `--delete_object` option config_update will only add/update new values but will *not* remove any entries missing in provided YAML input.
Users
-----
following are additional parameters that could be defined for users:
* comment
* quota_bytes
* global_admin
* enable_imap
* enable_pop
* forward_enabled
* forward_destination
* reply_enabled
* reply_subject
* reply_body
* displayed_name
* spam_enabled
* spam_threshold
Alias
-----
additional fields:
* wildcard

101
docs/cli.rst
Unescape Escape View File

@ -0,0 +1,101 @@
Mailu command line
==================
Managing users and aliases can be done from CLI using commands:
* alias
* alias_delete
* user
* user_import
* user_delete
* config_update
alias
-----
.. code-block:: bash
docker-compose run --rm admin python manage.py alias foo example.net "mail1@example.com,mail2@example.com"
alias_delete
------------
.. code-block:: bash
docker-compose run --rm admin python manage.py alias_delete foo@example.net
user
----
.. code-block:: bash
docker-compose run --rm admin python manage.py user --hash_scheme='SHA512-CRYPT' myuser example.net 'password123'
user_import
-----------
primary difference with simple `user` command is that password is being imported as a hash - very useful when migrating users from other systems where only hash is known.
.. code-block:: bash
docker-compose run --rm admin python manage.py user --hash_scheme='SHA512-CRYPT' myuser example.net '$6$51ebe0cb9f1dab48effa2a0ad8660cb489b445936b9ffd812a0b8f46bca66dd549fea530ce'
user_delete
------------
.. code-block:: bash
docker-compose run --rm admin python manage.py user_delete foo@example.net
config_update
-------------
This command sole purpose is for importing users/aliases in bulk and synchronizing DB entries with external YAML template:
.. code-block:: bash
cat mail-config.yml | docker-compose run --rm admin python manage.py config_update --delete_objects
where mail-config.yml looks like:
.. code-block:: bash
users:
- localpart: foo
domain: example.com
password_hash: klkjhumnzxcjkajahsdqweqqwr
hash_scheme: MD5-CRYPT
aliases:
- localpart: alias1
domain: example.com
destination: "user1@example.com,user2@example.com"
without ``--delete_object`` option config_update will only add/update new values but will *not* remove any entries missing in provided YAML input.
Users
-----
following are additional parameters that could be defined for users:
* comment
* quota_bytes
* global_admin
* enable_imap
* enable_pop
* forward_enabled
* forward_destination
* reply_enabled
* reply_subject
* reply_body
* displayed_name
* spam_enabled
* spam_threshold
Alias
-----
additional fields:
* wildcard

21
docs/compose/requirements.md → docs/compose/requirements.rst
Unescape Escape View File

@ -17,11 +17,13 @@ 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/).
any of the `officially supported distributions`_.
For the purpose of this guide, all examples are based on Debian Stretch. The
differences with other system will hardly be noticeable however.
.. _`officially supported distributions`: https://docs.docker.com/engine/installation/
Install the distribution
------------------------
@ -56,9 +58,10 @@ 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:
```
.. code-block:: bash
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
@ -73,19 +76,23 @@ 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/)
The Docker website is full of `detailed instructions`_
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
from the `Docker website`_ if you plan on using the CompComposesoe flavor. Compose is a
management tool for Docker, especially suited for multiple containers systems
like Mailu.
.. _`detailed instructions`: https://docs.docker.com/engine/installation/
.. _`Docker website`: https://docs.docker.com/compose/
Once everything is setup, you should be able to run the following commands
(exact version numbers do not matter):
```
.. code-block:: bash
$ docker version
Client:
Version: 1.11.2
@ -108,5 +115,3 @@ 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
```

21
docs/compose/setup.md → docs/compose/setup.rst
Unescape Escape View File

@ -7,10 +7,10 @@ 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:
```
.. code-block:: bash
mkdir /mailu
cd /mailu
```
Download the initial configuration file
---------------------------------------
@ -19,17 +19,16 @@ 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`:
```
.. code-block:: bash
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):
```
.. code-block:: bash
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``.
@ -101,7 +100,7 @@ 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
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.
@ -111,14 +110,14 @@ Start Mailu
You may now start Mailu. Move the to the Mailu directory and run:
```
.. code-block:: bash
docker-compose up -d
```
Finally, you must create the initial admin user account:
```
.. code-block:: bash
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.

5
docs/conf.py
Unescape Escape View File

@ -41,7 +41,7 @@ templates_path = ['_templates']
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.md'
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
@ -165,6 +165,3 @@ texinfo_documents = [
author, 'Mailu', 'One line description of project.',
'Miscellaneous'),
]

37
docs/configuration.md → docs/configuration.rst
Unescape Escape View File

@ -4,69 +4,68 @@ Mailu configuration settings
Common configuration
--------------------
The `SECRET_KEY` **must** be changed for every setup and set to a 16 bytes
The ``SECRET_KEY`` **must** be changed for every setup and set to a 16 bytes
randomly generated value. It is intended to secure authentication cookies
among other critical uses.
The `DOMAIN` holds the main e-mail domain for the server. This email domain
The ``DOMAIN`` holds the main e-mail domain for the server. This email domain
is used for bounce emails, for generating the postmaster email and other
technical addresses.
The `HOSTNAMES` are all public hostnames for the mail server. Mailu supports
The ``HOSTNAMES`` are all public hostnames for the mail server. Mailu supports
a mail server with multiple hostnames. The first declared hostname is the main
hostname and will be exposed over SMTP, IMAP, etc.
The `POSTMASTER` is the local part of the postmaster email address. It is
The ``POSTMASTER`` is the local part of the postmaster email address. It is
recommended to setup a generic value and later configure a mail alias for that
address.
The `AUTH_RATELIMIT` holds a security setting for fighting attackers that
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.
Mail settings
-------------
The `MESSAGE_SIZE_LIMIT` is the maximum size of a single email. It should not
The ``MESSAGE_SIZE_LIMIT`` is the maximum size of a single email. It should not
be too low to avoid dropping legitimate emails and should not be too high to
avoid filling the disks with large junk emails.
The `RELAYNETS` are network addresses for which mail is relayed for free with
The ``RELAYNETS`` are network addresses for which mail is relayed for free with
no authentication required. This should be used with great care. It is
recommended to include your Docker internal network addresses if other Docker
containers use Mailu as their mail relay.
The `RELAYHOST` is an optional address of a mail server relaying all outgoing
The ``RELAYHOST`` is an optional address of a mail server relaying all outgoing
mail.
The `FETCHMAIL_DELAY` is a delay (in seconds) for the fetchmail service to
The ``FETCHMAIL_DELAY`` is a delay (in seconds) for the fetchmail service to
go and fetch new email if available. Do not use too short delays if you do not
want to be blacklisted by external services, but not too long delays if you
want to receive your email in time.
The `RECIPIENT_DELIMITED` is a character used to delimit localpart from a
custom address part. For instance, if set to `+`, users can use addresses
like `localpart+custom@domain.tld` to deliver mail to `localpart@domain.tld`.
The ``RECIPIENT_DELIMITED`` is a character used to delimit localpart from a
custom address part. For instance, if set to ``+``, users can use addresses
like ``localpart+custom@domain.tld`` to deliver mail to ``localpart@domain.tld``.
This is useful to provide external parties with different email addresses and
later classify incoming mail based on the custom part.
The `DMAR_RUA` and `DMARC_RUF` are DMARC protocol specific values. They hold
The ``DMAR_RUA`` and ``DMARC_RUF`` are DMARC protocol specific values. They hold
the localpart for DMARC rua and ruf email addresses.
Web settings
------------
The `WEB_ADMIN` contains the path to the main admin interface, while
`WEB_WEBMAIL` contains the path to the Web email client.
The ``WEB_ADMIN`` contains the path to the main admin interface, while
``WEB_WEBMAIL`` contains the path to the Web email client.
Both `SITENAME` and `WEBSITE` are customization options for the panel menu
in the admin interface, while `SITENAME` is a customization option for
Both ``SITENAME`` and ``WEBSITE`` are customization options for the panel menu
in the admin interface, while ``SITENAME`` is a customization option for
every Web interface.
Advanced settings
-----------------
The `PASSWORD_SCHEME` is the password encryption scheme. You should use the
The ``PASSWORD_SCHEME`` is the password encryption scheme. You should use the
default value, unless you are importing password from a separate system and
want to keep using the old password encryption scheme.

12
docs/dns.md → docs/dns.rst
Unescape Escape View File

@ -16,9 +16,9 @@ You should pick a meaningful hostname that you can give your users to access the
Set that name in the ``HOSTNAME`` configuration entry. Then depending on your domain provider, make sure that you have an address record (``A``) serving the public IP address of your server:
```
.. code-block:: bash
mail.mydomain.com. IN A a.b.c.d
```
Also, ``a.b.c.d`` should be set in your ``BIND_INTERFACE`` configuration unless your server is in a DMZ and you are using port forwards to expose the services.
@ -33,16 +33,16 @@ For every domain that your mail server is responsible for, you must have a corre
To setup an ``MX`` record, exact actions will depend on your DNS provider and hoster, but assuming you are using a zone file, you should add for ``mydomain.com``:
```
.. code-block:: bash
mydomain.com. IN MX 10 mail.mydomain.com.
```
The number is the ``MX`` priority, which has little importance if you are running a single mail server but should be adjusted if you run a separate backup server.
And for another domain, ``myotherdomain.com`` for example:
```
.. code-block:: bash
myotherdomain.com. IN MX 10 mail.mydomain.com.
```
Note that both point to the same mail server hostname, which is unique to your server.

0
docs/general.md → docs/general.rst
Unescape Escape View File

1
docs/index.md → docs/index.rst
Unescape Escape View File

@ -12,7 +12,6 @@ The documentation is written as part of the repository and evolves with it.
Make sure that you access the proper version of the documentation, based on
the version of Mailu that you are running.
.. toctree::
:maxdepth: 2
:caption: Contents:

17
docs/kubernetes/index.md
Unescape Escape View File

@ -1,17 +0,0 @@
Kubernetes setup
================
Prepare the environment
-----------------------
The resource configurations in this folder assume that you have [Kubernetes Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) set up for your cluster. If you are not using the [NGINX Ingress Controller for Kubernetes](https://github.com/kubernetes/ingress/tree/master/controllers/nginx), please ensure that the configuration specified in the file matches your set up.
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.

22
docs/kubernetes/index.rst
Unescape Escape View File

@ -0,0 +1,22 @@
Kubernetes setup
================
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.

17
docs/maintain.md → docs/maintain.rst
Unescape Escape View File

@ -12,19 +12,19 @@ Update your ``.env`` file to reflect the version that you wish to install (if
you are running ``stable`` or ``latest``, you may skip this and proceed), then
simply pull the latest images and recreate the containers :
```
.. code-block:: bash
docker-compose pull
docker-compose up -d
```
Monitoring the mail server
--------------------------
Logs are managed by Docker directly. You can easily read your logs using :
```
.. code-block:: bash
docker-compose logs
```
Docker is able to forward logs to multiple log engines. Read the following documentation or details: https://docs.docker.com/engine/admin/logging/overview/.
@ -37,10 +37,9 @@ Mailu relys heavily on files for storing everything, which helps the migration p
The suggested migration process consists in setting up a new backup server that drops incoming emails (Mailu not started), synchronizing both servers, stopping the main server and launching the backup server. Then, the backup server is switched as a main MX and the old server is deleted.
1. Prepare your new server, copy your `docker-compose.yml`, `.env` and basic configuration files to the server, so that it is ready to start configuration Mailu, *do not start Mailu*
1. Prepare your new server, copy your ``docker-compose.yml``, ``.env`` and basic configuration files to the server, so that it is ready to start configuration Mailu, *do not start Mailu*
2. Setup your DNS so that the backup server is an additional, deprioritized MX for the domain; this can be complex if you serve many domains, in which case you can simply accept that some remote MX will retry for a couple minutes, skip this step
3. While your DNS TTL expires and your modification propagates, start *rsyncing* your Mailu directory (`data`, `dkim`, `mail`, etc.) to the new server, repeat until there are only a couple files synchronized
4. Stop Mailu on the old server and run a final `rsync` while no process is writing to the files
3. While your DNS TTL expires and your modification propagates, start *rsyncing* your Mailu directory (``data``, ``dkim``, ``mail``, etc.) to the new server, repeat until there are only a couple files synchronized
4. Stop Mailu on the old server and run a final ``rsync`` while no process is writing to the files
5. Start Mailu on the new server, and production should be back to normal
6. Set your new server as the main MX for your domains, if you did not set an additional MX, make sure you still change the `A` and `AAAA` record for your MX name.
6. Set your new server as the main MX for your domains, if you did not set an additional MX, make sure you still change the ``A`` and ``AAAA`` record for your MX name.

6
docs/setup.md → docs/setup.rst
Unescape Escape View File

@ -59,10 +59,12 @@ Make sure that you test properly before going live!
- Try to send an email to an external service
- On the external service, verify that DKIM and SPF are listed as passing
- Try to receive an email from an external service
- Check the logs (`docker-compose logs -f servicenamehere`) to look for
- Check the logs (``docker-compose logs -f servicenamehere``) to look for
warnings or errors
- Use an open relay checker like [MailRadar](http://www.mailradar.com/openrelay/)
- Use an open relay checker like `mailradar`_
to ensure you're not contributing to the spam problem on the internet.
All tests there should result in "Relay denied".
- If using DMARC, be sure to check the reports you get to verify that legitimate
email is getting through and forgeries are being properly blocked.
.. _mailradar: http://www.mailradar.com/openrelay/
Write Preview
Loading…
Cancel
Save