chore(docs): outsourcing environment vars to the documentation (#1948)

Co-authored-by: Frederic Werner <20406381+wernerfred@users.noreply.github.com>
Co-authored-by: Casper <casperklein@users.noreply.github.com>
Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com>

.github/ISSUE_TEMPLATE/config.yml

@@ -9,5 +9,5 @@ contact_links:
     url: https://github.com/docker-mailserver/docker-mailserver/blob/master/README.md
     about: Read this first and carefully
   - name: Environment Variables Section
-    url: https://github.com/docker-mailserver/docker-mailserver/blob/master/ENVIRONMENT.md
+    url: https://docker-mailserver.github.io/docker-mailserver/edge/config/environment/
     about: Read this section for information about mail server variables

.github/pull_request_template.md

@@ -1,13 +1,14 @@
 # Description
 
-<!-- Please include a summary of the change. Please also include relevant motivation and context. -->
+<!-- Include a summary of the change.
+     Please also include relevant motivation and context. -->
 
-<!-- Please link the issue which will be fixed (if any) here: -->
+<!-- Link the issue which will be fixed (if any) here: -->
-Fixes # (issue)
+Fixes #
 
 ## Type of change
 
-<!-- Please delete options that are not relevant. -->
+<!-- Delete options that are not relevant. -->
 
 - [ ] Bug fix (non-breaking change which fixes an issue)
 - [ ] New feature (non-breaking change which adds functionality)
@@ -20,6 +21,6 @@ Fixes # (issue)
 - [ ] My code follows the style guidelines of this project
 - [ ] I have performed a self-review of my own code
 - [ ] I have commented my code, particularly in hard-to-understand areas
-- [ ] I have made corresponding changes to the documentation (README.md or ENVIRONMENT.md or the documentation)
+- [ ] I have made corresponding changes to the documentation (README.md or the documentation under `docs/`)
 - [ ] If necessary I have added tests that prove my fix is effective or that my feature works
 - [ ] New and existing unit tests pass locally with my changes

CHANGELOG.md

@@ -7,7 +7,7 @@ This release marks the breakpoint where the wiki was transferred to a [reworked
 - **[feat]** Introduce ENABLE_AMAVIS env ([#1866](https://github.com/docker-mailserver/docker-mailserver/pull/1866))
 - **[docs]** Move wiki to gh-pages ([#1826](https://github.com/docker-mailserver/docker-mailserver/pull/1826)) - Special thanks to @polarathene 👨🏻‍💻
   - You can [edit the docs](https://github.com/docker-mailserver/docker-mailserver/tree/master/docs/content) now directly with your code changes
-  - Documentation is now versioned related to docker image versions and viewable here: https://docker-mailserver.github.io/docker-mailserver/edge/
+  - Documentation is now versioned related to docker image versions and viewable here: <https://docker-mailserver.github.io/docker-mailserver/edge/>
 
 ## `v9.0.1`
 
@@ -28,8 +28,7 @@ A small update on the notification function which was made more stable as well a
 - **[refactor]** Split `start-mailserver.sh` ([#1820](https://github.com/docker-mailserver/docker-mailserver/pull/1820))
 - **[fix]** Linting now uses local path to remove the sudo dependency ([#1831](https://github.com/docker-mailserver/docker-mailserver/pull/1831)).
 
-
+### Breaking Changes
-### Breaking Changes:
 
 - **[security]** TLS: `TLS_LEVEL=modern` has changed the server-side preference order to 128-bit before 256-bit encryption ([#1802](https://github.com/docker-mailserver/docker-mailserver/pull/1802)).
   - NOTE: This is still very secure but may result in misleading lower scores/grades from security audit websites.
@@ -40,7 +39,6 @@ A small update on the notification function which was made more stable as well a
 - **[refactor]** Complete refactoring of opendkim script ([#1812](https://github.com/docker-mailserver/docker-mailserver/pull/1812)).
   - NOTE: Use `./setup.sh config dkim help` to see the new syntax.
 
-
 ## `v8.0.1`
 
 This release is a hotfix for #1781.

CONTRIBUTING.md

@@ -32,7 +32,7 @@ The development workflow is the following:
 3. Add integration tests if necessary
 4. Get the linters with `make install_linters` and install `jq` with the package manager of your OS
 5. Use `make clean all` to build image locally and run tests (note that tests work on Linux **only**)
-6. Document your improvements if necessary (e.g. if you introduced new environment variables, write the description in [`ENVIRONMENT.md`](./ENVIRONMENT.md))
+6. Document your improvements if necessary (e.g. if you introduced new environment variables, describe those in the [ENV documentation](./docs/content/config/environment.md))
 7. [Commit][commit] and [sign your commit][gpg], push and create a pull-request to merge into `master`. Please **use the pull-request template** to provide a minimum of contextual information and make sure to meet the requirements of the checklist. 
    1. Pull requests are automatically tested against the CI and will be reviewed when tests pass
    2. When your changes are validated, your branch is merged

README.md

@@ -18,7 +18,7 @@ If you have issues, read the full `README` **and** the [documentation][documenta
 3. [Requirements](#requirements)
 4. [Usage](#usage)
 5. [Examples](#examples)
-6. [Environment Variables](./ENVIRONMENT.md)
+6. [Environment Variables](https://docker-mailserver.github.io/docker-mailserver/edge/config/environment/)
 7. [Documentation][documentation::web]
 8. [Release Notes](./CHANGELOG.md)
 
@@ -77,10 +77,9 @@ All workflows are using the **tagging convention** listed below. It is subsequen
 
 ### Get the tools
 
-Download `docker-compose.yml`, `compose.env`, `mailserver.env`
+Download `docker-compose.yml` and `mailserver.env`
 
 ``` BASH
-wget -O .env https://raw.githubusercontent.com/docker-mailserver/docker-mailserver/master/compose.env
 wget https://raw.githubusercontent.com/docker-mailserver/docker-mailserver/master/docker-compose.yml
 wget https://raw.githubusercontent.com/docker-mailserver/docker-mailserver/master/mailserver.env
 ```
@@ -90,8 +89,8 @@ and the `setup.sh` **in the correct version**
 ``` BASH
 # if you're using :edge as the image tag
 wget https://raw.githubusercontent.com/docker-mailserver/docker-mailserver/master/setup.sh
-# if you're using :latest (= :9.0.1) as the image tag
+# if you're using :latest (= :9.1.0) as the image tag
-wget https://raw.githubusercontent.com/docker-mailserver/docker-mailserver/v9.0.1/setup.sh
+wget https://raw.githubusercontent.com/docker-mailserver/docker-mailserver/v9.1.0/setup.sh
 
 chmod a+x ./setup.sh
 
@@ -103,20 +102,16 @@ chmod a+x ./setup.sh
 
 ### Create a docker-compose environment
 
-- [Install the latest docker-compose](https://docs.docker.com/compose/install/)
+1. [Install the latest docker-compose](https://docs.docker.com/compose/install/)
-- Edit the files `.env` and `mailserver.env` to your liking:
+2. Edit `docker-compose.yml` to your liking
-  - `.env` contains the configuration for Docker Compose
+   - substitute `<HOSTNAME>` and `<DOMAINNAME>` according to your domain
-  - `mailserver.env` contains the configuration for the mailserver container
+   - if you want to use SELinux for the `./config/:/tmp/docker-mailserver/` mount, append `-z` or `-Z`
-  - these files supports [only simple `VAR=VAL`](https://docs.docker.com/compose/env-file/)
+3. Configure the mailserver container to your liking by editing `mailserver.env` ([**Documentation**](https://docker-mailserver.github.io/docker-mailserver/edge/config/environment/))
-  - don't quote your values
+   - this file supports [_only_ simple `VAR=VAL`](https://docs.docker.com/compose/env-file/) (**don't** quote your values)
-  - variable substitution is *not* supported (e.g. `OVERRIDE_HOSTNAME=$HOSTNAME.$DOMAINNAME`).
+   - variable substitution is **not** supported (e.g. :no_entry_sign:`OVERRIDE_HOSTNAME=$HOSTNAME.$DOMAINNAME` :no_entry_sign:)
-- Variables in `.env` are expanded in the `docker-compose.yml` file **only** and **not** in the container. The file `mailserver.env` serves this case where environment variables are used in the container.
-- If you want to use a bare domain (host name = domain name), see [FAQ](https://docker-mailserver.github.io/docker-mailserver/edge/faq#can-i-use-nakedbare-domains-no-host-name)
 
 ### Get up and running
 
-If you'd like to use SELinux, add `-Z` to the variable `SELINUX_LABEL` in `.env`. If you want the volume bind mount to be shared among other containers switch `-Z` to `-z`
-
 ``` BASH
 docker-compose up -d mailserver
 
@@ -144,12 +139,26 @@ When keys are generated, you can configure your DNS server by just pasting the c
 
 #### Custom user changes & patches
 
-If you'd like to change, patch or alter files or behavior of `docker-mailserver`, you can use a script. See the [documentation](https://docker-mailserver.github.io/docker-mailserver/edge/config/advanced/user-patches/) for a detailed explanation.
+If you'd like to change, patch or alter files or behavior of `docker-mailserver`, you can use a script. See the [documentation](https://docker-mailserver.github.io/docker-mailserver/edge/config/advanced/override-defaults/user-patches/) for a detailed explanation.
+
+#### Updating `docker-mailserver`
+
+``` BASH
+docker-compose pull
+docker-compose down
+docker-compose up -d mailserver
+```
+
+You're done! And don't forget to have a look at the remaining functions of the `setup.sh` script with `./setup.sh help`.
 
 #### Supported Operating Systems
 
 We are currently providing support for Linux. Windows is _not_ supported and is known to cause problems. Similarly, macOS is _not officially_ supported - but you may get it to work there. In the end, Linux should be your preferred operating system for this image, especially when using this mailserver in production.
 
+#### Bare Domains
+
+If you want to use a bare domain (`hostname` == `domainname`), see [FAQ](https://docker-mailserver.github.io/docker-mailserver/edge/faq#can-i-use-nakedbare-domains-no-host-name).
+
 #### Support for Multiple Domains
 
 `docker-mailserver` supports multiple domains out of the box, so you can do this:
@@ -160,16 +169,6 @@ We are currently providing support for Linux. Windows is _not_ supported and is
 ./setup.sh email add user1@server.example.org
 ```
 
-#### Updating `docker-mailserver`
-
-``` BASH
-docker-compose down
-docker pull docker.io/mailserver/docker-mailserver:<VERSION TAG>
-docker-compose up -d mailserver
-```
-
-You're done! And don't forget to have a look at the remaining functions of the `setup.sh` script with `./setup.sh help`.
-
 #### SPF/Forwarding Problems
 
 If you got any problems with SPF and/or forwarding mails, give [SRS](https://github.com/roehling/postsrsd/blob/master/README.md) a try. You enable SRS by setting `ENABLE_SRS=1`. See the variable description for further information.
@@ -190,9 +189,9 @@ version: '3.8'
 services:
   mailserver:
     image: docker.io/mailserver/docker-mailserver:latest
-    hostname: mail          # ${HOSTNAME}
+    hostname: mail
-    domainname: domain.com  # ${DOMAINNAME}
+    domainname: example.com
-    container_name: mail    # ${CONTAINER_NAME}
+    container_name: mailserver
     ports:
       - "25:25"
       - "143:143"
@@ -231,9 +230,9 @@ version: '3.8'
 services:
   mailserver:
     image: docker.io/mailserver/docker-mailserver:latest
-    hostname: mail          # ${HOSTNAME}
+    hostname: mail
-    domainname: domain.com  # ${DOMAINNAME}
+    domainname: example.com
-    container_name: mail    # ${CONTAINER_NAME}
+    container_name: mailserver
     ports:
       - "25:25"
       - "143:143"

compose.env

@@ -1,14 +0,0 @@
-# –––––––––––––––––––––––––––––––––––––––––––––––
-# ––– Docker Compose Settings Variables –––––––––
-# –––––––––––––––––––––––––––––––––––––––––––––––
-
-HOSTNAME=<INSERT 'HOSTNAME' HERE>
-DOMAINNAME=<INSERT 'DOMAIN.TLD' HERE>
-CONTAINER_NAME=<INSERT 'CONTAINER NAME' HERE>
-
-# –––––––––––––––––––––––––––––––––––––––––––––––
-# ––– SELinux Compose File Settings Variables –––
-# ––– options: empty, '-z' or '-Z'  –––––––––––––
-# –––––––––––––––––––––––––––––––––––––––––––––––
-
-SELINUX_LABEL=

docker-compose.yml

@@ -3,9 +3,9 @@ version: '3.8'
 services:
   mailserver:
     image: docker.io/mailserver/docker-mailserver:latest
-    hostname: ${HOSTNAME}
+    hostname: <HOSTNAME> # <-- CHANGE THIS
-    domainname: ${DOMAINNAME}
+    domainname: <DOMAINNAME> # <-- CHANGE THIS
-    container_name: ${CONTAINER_NAME}
+    container_name: mailserver
     env_file: mailserver.env
     # To avoid conflicts with yaml base-60 float, DO NOT remove the quotation marks.
     # More information about the mailserver ports:
@@ -21,7 +21,7 @@ services:
       - mailstate:/var/mail-state
       - maillogs:/var/log/mail
       - /etc/localtime:/etc/localtime:ro
-      - ./config/:/tmp/docker-mailserver/${SELINUX_LABEL}
+      - ./config/:/tmp/docker-mailserver/
     restart: always
     stop_grace_period: 1m
     cap_add: [ "NET_ADMIN", "SYS_PTRACE" ]

docs/content/config/advanced/auth-ldap.md

@@ -12,7 +12,7 @@ Getting started with ldap and this mailserver we need to take 3 parts in account
 
 ## Variables to Control Provisioning by the Container
 
-Have a look at the [`ENVIRONMENT.md`][github-file-env] for information on the default values.
+Have a look at [the ENV page][docs-environment] for information on the default values.
 
 !!! example "postfix"
 
@@ -125,4 +125,4 @@ The following example illustrates this for a directory that has the qmail-schema
 - DOVECOT_USER_FILTER=(&(objectClass=qmailUser)(uid=%u)(accountStatus=active))
 ```
 
-[github-file-env]: https://github.com/docker-mailserver/docker-mailserver/blob/master/ENVIRONMENT.md
+[docs-environment]: ../environment.md

docs/content/config/environment.md

@@ -1,14 +1,18 @@
-# Environment
+---
+title: Environment Variables
+---
 
-## Variables
+!!! info
 
-1. Values in **bold** are the default values.
+    Values in **bold** are the default values. If an option doesn't work as documented here, check if you are running the latest image. The current `master` branch corresponds to the image `mailserver/docker-mailserver:edge`.
-2. If an option doesn't work as documented here, check if you are running the latest image. The current `master` branch corresponds to the image `mailserver/docker-mailserver:edge`.
-
-### Assignments
 
 #### General
 
+##### OVERRIDE_HOSTNAME
+
+- empty => uses the `hostname` command to get the mail server's canonical hostname.
+- => Specify a fully-qualified domainname to serve mail for.  This is used for many of the config features so if you can't set your hostname (e.g. you're in a container platform that doesn't let you) specify it in this environment variable.
+
 ##### DMS_DEBUG
 
 - **0** => Debug disabled
@@ -26,6 +30,23 @@ Here you can adjust the [log-level for Supervisor](http://supervisord.org/loggin
 
 The log-level will show everything in its class and above.
 
+
+##### ONE_DIR
+
+- **0** => state in default directories.
+- 1 => consolidate all states into a single directory (`/var/mail-state`) to allow persistence using docker volumes.
+
+##### PERMIT_DOCKER
+
+Set different options for mynetworks option (can be overwrite in postfix-main.cf) **WARNING**: Adding the docker network's gateway to the list of trusted hosts, e.g. using the `network` or `connected-networks` option, can create an [**open relay**](https://en.wikipedia.org/wiki/Open_mail_relay), for instance if IPv6 is enabled on the host machine but not in Docker.
+
+- **empty** => localhost only.
+- host => Add docker host (ipv4 only).
+- network => Add the docker default bridge network (172.16.0.0/12); **WARNING**: `docker-compose` might use others (e.g. 192.168.0.0/16) use `PERMIT_DOCKER=connected-networks` in this case.
+- connected-networks => Add all connected docker networks (ipv4 only).
+
+Note: you probably want to [set `POSTFIX_INET_PROTOCOLS=ipv4`](#postfix_inet_protocols) to make it work fine with Docker.
+
 ##### ENABLE_AMAVIS
 
 Amavis content filter (used for ClamAV & SpamAssassin)
@@ -47,11 +68,6 @@ Amavis content filter (used for ClamAV & SpamAssassin)
 - **0** => Clamav is disabled
 - 1 => Clamav is enabled
 
-##### ONE_DIR
-
-- **0** => state in default directories
-- 1 => consolidate all states into a single directory (`/var/mail-state`) to allow persistence using docker volumes
-
 ##### ENABLE_POP3
 
 - **empty** => POP3 service disabled
@@ -114,17 +130,6 @@ Enables the Sender Rewriting Scheme. SRS is needed if your mail server acts as f
 - **0** => Disabled
 - 1 => Enabled
 
-##### PERMIT_DOCKER
-
-Set different options for mynetworks option (can be overwrite in postfix-main.cf) **WARNING**: Adding the docker network's gateway to the list of trusted hosts, e.g. using the `network` or `connected-networks` option, can create an [**open relay**](https://en.wikipedia.org/wiki/Open_mail_relay), for instance if IPv6 is enabled on the host machine but not in Docker.
-
-- **empty** => localhost only
-- host => Add docker host (ipv4 only)
-- network => Add the docker default bridge network (172.16.0.0/12); **WARNING**: `docker-compose` might use others (e.g. 192.168.0.0/16) use `PERMIT_DOCKER=connected-networks` in this case
-- connected-networks => Add all connected docker networks (ipv4 only)
-
-Note: you probably want to [set `POSTFIX_INET_PROTOCOLS=ipv4`](#postfix_inet_protocols) to make it work fine with Docker.
-
 ##### NETWORK_INTERFACE
 
 In case your network interface differs from `eth0`, e.g. when you are using HostNetworking in Kubernetes, you can set this to whatever interface you want. This interface will then be used.
@@ -491,7 +496,7 @@ The following variables overwrite the default values for ```/etc/dovecot/dovecot
 
 - e.g. `homeDirectory=home,qmailUID=uid,qmailGID=gid,mailMessageStore=mail`
 - => Specify the directory to dovecot attribute mapping that fits your directory structure.
-- Note: This is necessary for directories that do not use the [Postfix Book Schema](test/docker-openldap/bootstrap/schema/mmc/postfix-book.schema).
+- Note: This is necessary for directories that do not use the Postfix Book Schema.
 - Note: The left-hand value is the directory attribute, the right hand value is the dovecot variable.
 - More details on the [Dovecot Wiki](https://wiki.dovecot.org/AuthDatabase/LDAP/Userdb)
 
@@ -504,7 +509,7 @@ The following variables overwrite the default values for ```/etc/dovecot/dovecot
 
 - e.g. `uid=user,userPassword=password`
 - => Specify the directory to dovecot variable mapping that fits your directory structure.
-- Note: This is necessary for directories that do not use the [Postfix Book Schema](test/docker-openldap/bootstrap/schema/mmc/postfix-book.schema).
+- Note: This is necessary for directories that do not use the Postfix Book Schema.
 - Note: The left-hand value is the directory attribute, the right hand value is the dovecot variable.
 - More details on the [Dovecot Wiki](https://wiki.dovecot.org/AuthDatabase/LDAP/PasswordLookups)
 

docs/content/config/security/ssl.md

@@ -195,9 +195,9 @@ The second part of the setup is the actual mail container. So, in another folder
     services:
       mailserver:
         image: mailserver/docker-mailserver:latest
-        hostname: ${HOSTNAME}
+        hostname: <HOSTNAME> # <-- change this
-        domainname: ${DOMAINNAME}
+        domainname: <DOMAINNAME> # <-- change this
-        container_name: ${CONTAINER_NAME}
+        container_name: mailserver
         ports:
           - "25:25"
           - "143:143"

docs/content/config/setup.sh.md

@@ -21,70 +21,113 @@ chmod a+x ./setup.sh
 
 Run `./setup.sh help` and you'll get some usage information:
 
-```bash
+```TXT
-setup.sh Bootstrapping Script
+SETUP(1)
 
-Usage: ./setup.sh [-i IMAGE_NAME] [-c CONTAINER_NAME] <subcommand> <subcommand> [args]
+NAME
+    setup.sh - docker-mailserver administration script
 
-OPTIONS:
+SYNOPSIS
+    ./setup.sh [ OPTIONS... ] COMMAND [ help | ARGUMENTS... ]
 
-  -i IMAGE_NAME     The name of the docker-mailserver image
+    COMMAND := { email | alias | quota | config | relay | debug } SUBCOMMAND
-                    The default value is
-                    'docker.io/mailserver/docker-mailserver:latest'
 
-  -c CONTAINER_NAME The name of the running container.
+DESCRIPTION
+    This is the main administration script that you use for all interactions with your
+    mail server. Setup, configuration and much more is done with this script.
 
-  -p PATH           Config folder path (default: /home/georg/github/docker-mailserver/config)
+    Please note that the script executes most of the commands inside the container itself.
+    If the image was not found, this script will pull the :latest tag of
+    mailserver/docker-mailserver. This tag refers to the latest release,
+    see the tagging convention in the README under
+    https://github.com/docker-mailserver/docker-mailserver/blob/master/README.md
 
-  -h                Show this help dialogue
+    You will be able to see detailed information about the script you are invoking and
+    its arguments by appending help after your command. Currently, this
+    does not work with all scripts.
 
-  -z                Allow container access to the bind mount content
+VERSION
-                    that is shared among multiple containers
+    The current version of this script is backwards compatible with versions of
-                    on a SELinux-enabled host.
+    docker-mailserver after 8.0.1. In case that there is not a more recent release,
+    this script is currently only working with the :edge tag.
 
-  -Z                Allow container access to the bind mount content
+    You can download the script for your release by substituting TAG from the
-                    that is private and unshared with other containers
+    following URL, where TAG looks like 'vX.X.X':
-                    on a SELinux-enabled host.
+    https://raw.githubusercontent.com/docker-mailserver/docker-mailserver/TAG/setup.sh
 
-SUBCOMMANDS:
+OPTIONS
+    Config path, container or image adjustments
+        -i IMAGE_NAME
+            Provides the name of the docker-mailserver image. The default value is
+            docker.io/mailserver/docker-mailserver:latest
 
-  email:
+        -c CONTAINER_NAME
+            Provides the name of the running container.
 
-    ./setup.sh email add <email> [<password>]
+        -p PATH
-    ./setup.sh email update <email> [<password>]
+            Provides the config folder path. The default is
-    ./setup.sh email del <email>
+            /home/maxwell/Dokumente/github/docker-mailserver/config/
-    ./setup.sh email restrict <add|del|list> <send|receive> [<email>]
+
+    SELinux
+        -z
+            Allows container access to the bind mount content that is shared among
+            multiple containers on a SELinux-enabled host.
+
+        -Z
+            Allows container access to the bind mount content that is private and
+            unshared with other containers on a SELinux-enabled host.
+
+[SUB]COMMANDS
+    COMMAND email :=
+        ./setup.sh email add <EMAIL ADDRESS> [<PASSWORD>]
+        ./setup.sh email update <EMAIL ADDRESS> [<PASSWORD>]
+        ./setup.sh email del [ OPTIONS... ] <EMAIL ADDRESS> [ <EMAIL ADDRESS>... ]
+        ./setup.sh email restrict <add|del|list> <send|receive> [<EMAIL ADDRESS>]
         ./setup.sh email list
 
-  alias:
+    COMMAND alias :=
-    ./setup.sh alias add <email> <recipient>
+        ./setup.sh alias add <EMAIL ADDRESS> <RECIPIENT>
-    ./setup.sh alias del <email> <recipient>
+        ./setup.sh alias del <EMAIL ADDRESS> <RECIPIENT>
         ./setup.sh alias list
 
-  quota:
+    COMMAND quota :=
-    ./setup.sh quota set <email> [<quota>]
+        ./setup.sh quota set <EMAIL ADDRESS> [<QUOTA>]
-    ./setup.sh quota del <email>
+        ./setup.sh quota del <EMAIL ADDRESS>
 
-  config:
+    COMMAND config :=
+        ./setup.sh config dkim [ ARGUMENTS... ]
+        ./setup.sh config ssl <FQDN> (ATTENTION: This is deprecated and will be removed soon.)
 
-    ./setup.sh config dkim <keysize> (default: 4096) <domain.tld> (optional - for LDAP setups)
+    COMMAND relay :=
-    ./setup.sh config ssl <fqdn>
+        ./setup.sh relay add-domain <DOMAIN> <HOST> [<PORT>]
-
+        ./setup.sh relay add-auth <DOMAIN> <USERNAME> [<PASSWORD>]
-  relay:
+        ./setup.sh relay exclude-domain <DOMAIN>
-
-    ./setup.sh relay add-domain <domain> <host> [<port>]
-    ./setup.sh relay add-auth <domain> <username> [<password>]
-    ./setup.sh relay exclude-domain <domain>
-
-  debug:
 
+    COMMAND debug :=
         ./setup.sh debug fetchmail
-    ./setup.sh debug fail2ban [<unban> <ip-address>]
+        ./setup.sh debug fail2ban [unban <IP>]
         ./setup.sh debug show-mail-logs
         ./setup.sh debug inspect
-    ./setup.sh debug login <commands>
+        ./setup.sh debug login <COMMANDS>
+
+EXAMPLES
+    ./setup.sh email add test@domain.tld
+        Add the email account test@domain.tld. You will be prompted
+        to input a password afterwards since no password was supplied.
+
+    ./setup.sh config dkim keysize 2048 domain 'whoami.com,whoareyou.org'
+        Creates keys of length 2048 but in an LDAP setup where domains are not known to
+        Postfix by default, so you need to provide them yourself in a comma-separated list.
+
+    ./setup.sh config dkim help
+        This will provide you with a detailed explanation on how to use the 
+        config dkim command, showing what arguments can be passed and what they do.
+
+EXIT STATUS
+    Exit status is 0 if the command was successful. If there was an unexpected error, an error
+    message is shown describing the error. In case of an error, the script will exit with exit
+    status 1.
 
-  help: Show this help dialogue
 ```
 
 [github-file-setupsh]: https://github.com/docker-mailserver/docker-mailserver/blob/master/setup.sh

docs/content/config/troubleshooting/debugging.md

@@ -7,7 +7,7 @@ title: 'Troubleshooting | Debugging'
 
 ## Enable Verbose Debugging Output
 
-You may find it useful to enable the [`DMS_DEBUG`][github-file-env-dmsdebug] environment variable.
+You may find it useful to enable the [`DMS_DEBUG`][docs-environment-dmsdebug] environment variable.
 
 ## Invalid Username or Password
 
@@ -58,7 +58,8 @@ fail2ban-client stop postfix
 Some hosting provides have a stealth block on port 25. Make sure to check with your hosting provider that traffic on port 25 is allowed
 
 Common hosting providers known to have this issue:
+
 - [Azure](https://docs.microsoft.com/en-us/azure/virtual-network/troubleshoot-outbound-smtp-connectivity)
 - [AWS EC2](https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/)
 
-[github-file-env-dmsdebug]: https://github.com/docker-mailserver/docker-mailserver/blob/master/ENVIRONMENT.md#dms_debug
+[docs-environment-dmsdebug]: ../environment.md#dms_debug

docs/content/contributing/coding-style.md

@@ -51,7 +51,7 @@ If you forgot this and want to change it later, you can use [this link][regex].
 local VAR="good"
 local NEW="${VAR}"
 
-# bad -> TravisCI will fail
+# bad -> CI will fail
 var="bad"
 new=$var
 ```

docs/content/contributing/issues-and-pull-requests.md

@@ -37,7 +37,7 @@ The development workflow is the following:
 3. Add integration tests if necessary
 4. Get the linters with `make install_linters` and install `jq` with the package manager of your OS
 5. Use `make clean all` to build image locally and run tests (note that tests work on Linux **only**)
-6. Document your improvements if necessary (e.g. if you introduced new environment variables, write the description in [`ENVIRONMENT.md`][github-file-env])
+6. Document your improvements if necessary (e.g. if you introduced new environment variables, describe those in the [ENV documentation][docs-environment])
 7. [Commit][commit] and [sign your commit][gpg], push and create a pull-request to merge into `master`. Please **use the pull-request template** to provide a minimum of contextual information and make sure to meet the requirements of the checklist. 
    1. Pull requests are automatically tested against the CI and will be reviewed when tests pass
    2. When your changes are validated, your branch is merged
@@ -45,6 +45,6 @@ The development workflow is the following:
 
 [docs]: https://docker-mailserver.github.io/docker-mailserver/edge
 [github-file-readme]: https://github.com/docker-mailserver/docker-mailserver/blob/master/README.md
-[github-file-env]: https://github.com/docker-mailserver/docker-mailserver/blob/master/ENVIRONMENT.md
+[docs-environment]: ../config/environment.md
 [commit]: https://help.github.com/articles/closing-issues-via-commit-messages/
 [gpg]: https://docs.github.com/en/github/authenticating-to-github/generating-a-new-gpg-key

docs/content/examples/tutorials/basic-installation.md

@@ -60,7 +60,7 @@ We are going to use this docker based mailserver:
 
     For more details about the environment variables that can be used, and their meaning and possible values, check also these:
 
-    - [Environtment Variables][github-file-env]
+    - [Environment Variables][docs-environment]
     - [`mailserver.env` file][github-file-dotenv]
 
     Make sure to set the proper `domainname` that you will use for the emails. We forward only SMTP ports (not POP3 and IMAP) because we are not interested in accessing the mailserver directly (from a client).  We also use these settings:
@@ -157,6 +157,6 @@ We are going to use this docker based mailserver:
     - **SMTP username**: `info@example.org`
     - **SMTP password**: `passwd123`
 
-[github-file-env]: https://github.com/docker-mailserver/docker-mailserver/blob/master/ENVIRONMENT.md
+[docs-environment]: ../../config/environment.md
 [github-file-dotenv]: https://github.com/docker-mailserver/docker-mailserver/blob/master/mailserver.env
 [github-issue-1405-comment]: https://github.com/docker-mailserver/docker-mailserver/issues/1405#issuecomment-590106498

docs/content/index.md

@@ -12,7 +12,7 @@ This documentation provides you with advanced configuration, detailed examples,
 
 1. The script [`setup.sh`][github-file-setupsh] is supplied with this project. It supports you in **configuring and administrating** your server. Information on how to get it and how to use it is available [on a dedicated page][docs-setupsh].
 2. Be aware that advanced tasks may still require tweaking environment variables, reading through documentation and sometimes inspecting your running container for debugging purposes. After all, a mail server is a complex arrangement of various programs.
-3. A list of all configuration options is provided in [`ENVIRONMENT.md`][github-file-env]. The [`README.md`][github-file-readme] is a good starting point to understand what this image is capable of.
+3. A list of all configuration options is documented on [the ENV page][docs-environment]. The [`README.md`][github-file-readme] is a good starting point to understand what this image is capable of.
 4. A list of all optional and automatically created configuration files and directories is available [on the dedicated page][docs-optionalconfig].
 
 !!! tip
@@ -30,6 +30,6 @@ We are always happy to welcome new contributors. For guidelines and entrypoints
 [docs-optionalconfig]: ./config/advanced/optional-config.md
 [docs-setupsh]: ./config/setup.sh.md
 [docs-userpatches]: ./config/advanced/override-defaults/user-patches.md
+[docs-environment]: ./config/environment.md
 [github-file-readme]: https://github.com/docker-mailserver/docker-mailserver/blob/master/README.md
-[github-file-env]: https://github.com/docker-mailserver/docker-mailserver/blob/master/ENVIRONMENT.md
 [github-file-setupsh]: https://github.com/docker-mailserver/docker-mailserver/blob/master/setup.sh

docs/mkdocs.yml

@@ -106,6 +106,7 @@ nav:
   - 'Introduction': introduction.md
   - 'Configuration':
     - 'Your Best Friend setup.sh': config/setup.sh.md
+    - 'Environment Variables': config/environment.md
     - 'User Management':
       - 'Accounts': config/user-management/accounts.md
       - 'Aliases': config/user-management/aliases.md

mailserver.env

@@ -2,6 +2,13 @@
 # ––– Mailserver Environment Variables ––––––––––
 # –––––––––––––––––––––––––––––––––––––––––––––––
 
+# DOCUMENTATION FOR THESE VARIABLES IS FOUND UNDER
+# https://docker-mailserver.github.io/docker-mailserver/edge/config/environment/
+
+# –––––––––––––––––––––––––––––––––––––––––––––––
+# ––– General Section –––––––––––––––––––––––––––
+# –––––––––––––––––––––––––––––––––––––––––––––––
+
 # empty => uses the `hostname` command to get the mail server's canonical hostname
 # => Specify a fully-qualified domainname to serve mail for.  This is used for many of the config features so if you can't set your hostname (e.g. you're in a container platform that doesn't let you) specify it in this environment variable.
 OVERRIDE_HOSTNAME=