From fcf9515bff8dda0646256f677d3cc03e1b7f4c6f Mon Sep 17 00:00:00 2001 From: kaiyou Date: Thu, 2 Nov 2017 20:05:12 +0100 Subject: [PATCH] Fix the rst syntax for most documentation --- docs/cli.md | 102 ------------------ docs/cli.rst | 101 +++++++++++++++++ .../{requirements.md => requirements.rst} | 61 ++++++----- docs/compose/{setup.md => setup.rst} | 37 ++++--- docs/conf.py | 5 +- docs/{configuration.md => configuration.rst} | 37 ++++--- docs/{dns.md => dns.rst} | 18 ++-- docs/{general.md => general.rst} | 0 docs/{index.md => index.rst} | 1 - docs/kubernetes/index.md | 17 --- docs/kubernetes/index.rst | 22 ++++ docs/{maintain.md => maintain.rst} | 23 ++-- docs/{setup.md => setup.rst} | 6 +- 13 files changed, 217 insertions(+), 213 deletions(-) delete mode 100644 docs/cli.md create mode 100644 docs/cli.rst rename docs/compose/{requirements.md => requirements.rst} (75%) rename docs/compose/{setup.md => setup.rst} (85%) rename docs/{configuration.md => configuration.rst} (54%) rename docs/{dns.md => dns.rst} (93%) rename docs/{general.md => general.rst} (100%) rename docs/{index.md => index.rst} (99%) delete mode 100644 docs/kubernetes/index.md create mode 100644 docs/kubernetes/index.rst rename docs/{maintain.md => maintain.rst} (74%) rename docs/{setup.md => setup.rst} (94%) diff --git a/docs/cli.md b/docs/cli.md deleted file mode 100644 index cccebfb4..00000000 --- a/docs/cli.md +++ /dev/null @@ -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 - diff --git a/docs/cli.rst b/docs/cli.rst new file mode 100644 index 00000000..9b1b4089 --- /dev/null +++ b/docs/cli.rst @@ -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 diff --git a/docs/compose/requirements.md b/docs/compose/requirements.rst similarity index 75% rename from docs/compose/requirements.md rename to docs/compose/requirements.rst index bff38417..1cb00b1d 100644 --- a/docs/compose/requirements.md +++ b/docs/compose/requirements.rst @@ -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: -``` -apt-get autoremove --purge exim4 exim4-base -``` +.. 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,40 +76,42 @@ 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): -``` -$ docker version -Client: - Version: 1.11.2 - API version: 1.23 - Go version: go1.6.2 - Git commit: b9f10c9 - Built: Sun Jun 5 23:17:55 2016 - OS/Arch: linux/amd64 +.. code-block:: bash -Server: - Version: 1.11.1 - API version: 1.23 - Go version: go1.6.2 - Git commit: 5604cbe - Built: Mon May 2 00:06:51 2016 - OS/Arch: linux/amd64 + $ docker version + Client: + Version: 1.11.2 + API version: 1.23 + Go version: go1.6.2 + Git commit: b9f10c9 + Built: Sun Jun 5 23:17:55 2016 + OS/Arch: linux/amd64 -$ docker-compose version -docker-compose version 1.7.1, build 6c29830 -docker-py version: 1.8.1 -CPython version: 3.5.1 -OpenSSL version: OpenSSL 1.0.2h 3 May 2016 -``` + Server: + Version: 1.11.1 + API version: 1.23 + Go version: go1.6.2 + Git commit: 5604cbe + Built: Mon May 2 00:06:51 2016 + OS/Arch: linux/amd64 + $ docker-compose version + docker-compose version 1.7.1, build 6c29830 + docker-py version: 1.8.1 + CPython version: 3.5.1 + OpenSSL version: OpenSSL 1.0.2h 3 May 2016 diff --git a/docs/compose/setup.md b/docs/compose/setup.rst similarity index 85% rename from docs/compose/setup.md rename to docs/compose/setup.rst index c5ff86ec..b3d12de9 100644 --- a/docs/compose/setup.md +++ b/docs/compose/setup.rst @@ -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: -``` -mkdir /mailu -cd /mailu -``` +.. 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`: -``` -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 -``` +.. 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): -``` -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 -``` +.. 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: -``` -docker-compose up -d -``` +.. code-block:: bash + + docker-compose up -d Finally, you must create the initial admin user account: -``` -docker-compose run --rm admin python manage.py admin root example.net password -``` +.. 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. diff --git a/docs/conf.py b/docs/conf.py index 5c3dd1a1..e2ac758b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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'), ] - - - diff --git a/docs/configuration.md b/docs/configuration.rst similarity index 54% rename from docs/configuration.md rename to docs/configuration.rst index ba674540..5e192653 100644 --- a/docs/configuration.md +++ b/docs/configuration.rst @@ -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. - diff --git a/docs/dns.md b/docs/dns.rst similarity index 93% rename from docs/dns.md rename to docs/dns.rst index 6109e6d8..17e566b3 100644 --- a/docs/dns.md +++ b/docs/dns.rst @@ -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: -``` -mail.mydomain.com. IN A a.b.c.d -``` +.. 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``: -``` -mydomain.com. IN MX 10 mail.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: -``` -myotherdomain.com. IN MX 10 mail.mydomain.com. -``` +.. 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. diff --git a/docs/general.md b/docs/general.rst similarity index 100% rename from docs/general.md rename to docs/general.rst diff --git a/docs/index.md b/docs/index.rst similarity index 99% rename from docs/index.md rename to docs/index.rst index f388e05b..6160dfb3 100644 --- a/docs/index.md +++ b/docs/index.rst @@ -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: diff --git a/docs/kubernetes/index.md b/docs/kubernetes/index.md deleted file mode 100644 index 3a2488f0..00000000 --- a/docs/kubernetes/index.md +++ /dev/null @@ -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..tld/admin` (note that visiting just `mail..tld` will likely result in a 404. diff --git a/docs/kubernetes/index.rst b/docs/kubernetes/index.rst new file mode 100644 index 00000000..21effb6b --- /dev/null +++ b/docs/kubernetes/index.rst @@ -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..tld/admin`` (note that visiting just ``mail..tld`` will likely result in a 404. diff --git a/docs/maintain.md b/docs/maintain.rst similarity index 74% rename from docs/maintain.md rename to docs/maintain.rst index 18b51f97..e14d911c 100644 --- a/docs/maintain.md +++ b/docs/maintain.rst @@ -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 : -``` -docker-compose pull -docker-compose up -d -``` +.. 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 : -``` -docker-compose logs -``` +.. 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. diff --git a/docs/setup.md b/docs/setup.rst similarity index 94% rename from docs/setup.md rename to docs/setup.rst index 658e3f5d..63d60072 100644 --- a/docs/setup.md +++ b/docs/setup.rst @@ -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/