diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index ed2eb258..0091c97d 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.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 diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 9e6fda57..bcdf248a 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,13 +1,14 @@ # Description - + - -Fixes # (issue) + +Fixes # ## Type of change - + - [ ] 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 diff --git a/CHANGELOG.md b/CHANGELOG.md index d39693b5..a43a53cc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,9 +5,9 @@ This release marks the breakpoint where the wiki was transferred to a [reworked documentation](https://docker-mailserver.github.io/docker-mailserver/edge/) - **[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 👨🏻‍💻 +- **[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: ## `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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 44465d0f..d7abdfcc 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/README.md b/README.md index 795dae70..73520916 100644 --- a/README.md +++ b/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 -wget https://raw.githubusercontent.com/docker-mailserver/docker-mailserver/v9.0.1/setup.sh +# if you're using :latest (= :9.1.0) as the image tag +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/) -- Edit the files `.env` and `mailserver.env` to your liking: - - `.env` contains the configuration for Docker Compose - - `mailserver.env` contains the configuration for the mailserver container - - these files 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`). -- 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) +1. [Install the latest docker-compose](https://docs.docker.com/compose/install/) +2. Edit `docker-compose.yml` to your liking + - substitute `` and `` according to your domain + - if you want to use SELinux for the `./config/:/tmp/docker-mailserver/` mount, append `-z` or `-Z` +3. Configure the mailserver container to your liking by editing `mailserver.env` ([**Documentation**](https://docker-mailserver.github.io/docker-mailserver/edge/config/environment/)) + - 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. :no_entry_sign:`OVERRIDE_HOSTNAME=$HOSTNAME.$DOMAINNAME` :no_entry_sign:) ### 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: -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} - domainname: domain.com # ${DOMAINNAME} - container_name: mail # ${CONTAINER_NAME} + hostname: mail + domainname: example.com + 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} - domainname: domain.com # ${DOMAINNAME} - container_name: mail # ${CONTAINER_NAME} + hostname: mail + domainname: example.com + container_name: mailserver ports: - "25:25" - "143:143" diff --git a/compose.env b/compose.env deleted file mode 100644 index 6597ef8c..00000000 --- a/compose.env +++ /dev/null @@ -1,14 +0,0 @@ -# ––––––––––––––––––––––––––––––––––––––––––––––– -# ––– Docker Compose Settings Variables ––––––––– -# ––––––––––––––––––––––––––––––––––––––––––––––– - -HOSTNAME= -DOMAINNAME= -CONTAINER_NAME= - -# ––––––––––––––––––––––––––––––––––––––––––––––– -# ––– SELinux Compose File Settings Variables ––– -# ––– options: empty, '-z' or '-Z' ––––––––––––– -# ––––––––––––––––––––––––––––––––––––––––––––––– - -SELINUX_LABEL= diff --git a/docker-compose.yml b/docker-compose.yml index 26c475e7..fc75f754 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -3,9 +3,9 @@ version: '3.8' services: mailserver: image: docker.io/mailserver/docker-mailserver:latest - hostname: ${HOSTNAME} - domainname: ${DOMAINNAME} - container_name: ${CONTAINER_NAME} + hostname: # <-- CHANGE THIS + domainname: # <-- CHANGE THIS + 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" ] diff --git a/docs/content/config/advanced/auth-ldap.md b/docs/content/config/advanced/auth-ldap.md index 91f4efba..81481ac8 100644 --- a/docs/content/config/advanced/auth-ldap.md +++ b/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 diff --git a/ENVIRONMENT.md b/docs/content/config/environment.md similarity index 95% rename from ENVIRONMENT.md rename to docs/content/config/environment.md index 1cb66a40..0220fbde 100644 --- a/ENVIRONMENT.md +++ b/docs/content/config/environment.md @@ -1,14 +1,18 @@ -# Environment +--- +title: Environment Variables +--- -## Variables +!!! info -1. Values in **bold** are the default values. -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 + 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`. #### 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) diff --git a/docs/content/config/security/ssl.md b/docs/content/config/security/ssl.md index 7de8c312..a28bb0f8 100644 --- a/docs/content/config/security/ssl.md +++ b/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} - domainname: ${DOMAINNAME} - container_name: ${CONTAINER_NAME} + hostname: # <-- change this + domainname: # <-- change this + container_name: mailserver ports: - "25:25" - "143:143" diff --git a/docs/content/config/setup.sh.md b/docs/content/config/setup.sh.md index 48b99498..db91a373 100644 --- a/docs/content/config/setup.sh.md +++ b/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 -setup.sh Bootstrapping Script +```TXT +SETUP(1) -Usage: ./setup.sh [-i IMAGE_NAME] [-c CONTAINER_NAME] [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 - The default value is - 'docker.io/mailserver/docker-mailserver:latest' + COMMAND := { email | alias | quota | config | relay | debug } SUBCOMMAND - -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 - that is shared among multiple containers - on a SELinux-enabled host. +VERSION + The current version of this script is backwards compatible with versions of + 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 - that is private and unshared with other containers - on a SELinux-enabled host. + You can download the script for your release by substituting TAG from the + following URL, where TAG looks like 'vX.X.X': + 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 [] - ./setup.sh email update [] - ./setup.sh email del - ./setup.sh email restrict [] - ./setup.sh email list + -p PATH + Provides the config folder path. The default is + /home/maxwell/Dokumente/github/docker-mailserver/config/ - alias: - ./setup.sh alias add - ./setup.sh alias del - ./setup.sh alias list + SELinux + -z + Allows container access to the bind mount content that is shared among + multiple containers on a SELinux-enabled host. - quota: - ./setup.sh quota set [] - ./setup.sh quota del + -Z + Allows container access to the bind mount content that is private and + unshared with other containers on a SELinux-enabled host. - config: +[SUB]COMMANDS + COMMAND email := + ./setup.sh email add [] + ./setup.sh email update [] + ./setup.sh email del [ OPTIONS... ] [ ... ] + ./setup.sh email restrict [] + ./setup.sh email list - ./setup.sh config dkim (default: 4096) (optional - for LDAP setups) - ./setup.sh config ssl + COMMAND alias := + ./setup.sh alias add + ./setup.sh alias del + ./setup.sh alias list - relay: + COMMAND quota := + ./setup.sh quota set [] + ./setup.sh quota del - ./setup.sh relay add-domain [] - ./setup.sh relay add-auth [] - ./setup.sh relay exclude-domain + COMMAND config := + ./setup.sh config dkim [ ARGUMENTS... ] + ./setup.sh config ssl (ATTENTION: This is deprecated and will be removed soon.) - debug: + COMMAND relay := + ./setup.sh relay add-domain [] + ./setup.sh relay add-auth [] + ./setup.sh relay exclude-domain - ./setup.sh debug fetchmail - ./setup.sh debug fail2ban [ ] - ./setup.sh debug show-mail-logs - ./setup.sh debug inspect - ./setup.sh debug login + COMMAND debug := + ./setup.sh debug fetchmail + ./setup.sh debug fail2ban [unban ] + ./setup.sh debug show-mail-logs + ./setup.sh debug inspect + ./setup.sh debug login + +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 diff --git a/docs/content/config/troubleshooting/debugging.md b/docs/content/config/troubleshooting/debugging.md index 0c7deb87..71450aa8 100644 --- a/docs/content/config/troubleshooting/debugging.md +++ b/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 diff --git a/docs/content/contributing/coding-style.md b/docs/content/contributing/coding-style.md index c8daf96b..762c5daa 100644 --- a/docs/content/contributing/coding-style.md +++ b/docs/content/contributing/coding-style.md @@ -2,7 +2,7 @@ title: 'Contributing | Coding Style' --- -##Bash and Shell +## Bash and Shell When refactoring, writing or altering scripts, that is Shell and bash scripts, in any way, adhere to these rules: @@ -40,7 +40,7 @@ fi ### Variables & Braces -!!! attention +!!! attention Variables are always uppercase. We always use braces. @@ -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 ``` diff --git a/docs/content/contributing/issues-and-pull-requests.md b/docs/content/contributing/issues-and-pull-requests.md index 6ae3cb48..38fe3184 100644 --- a/docs/content/contributing/issues-and-pull-requests.md +++ b/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 diff --git a/docs/content/examples/tutorials/basic-installation.md b/docs/content/examples/tutorials/basic-installation.md index f1ebacae..1a47d770 100644 --- a/docs/content/examples/tutorials/basic-installation.md +++ b/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 diff --git a/docs/content/index.md b/docs/content/index.md index eba7bd00..e6ee43db 100644 --- a/docs/content/index.md +++ b/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 diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 1cee8810..1dd41957 100644 --- a/docs/mkdocs.yml +++ b/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 diff --git a/mailserver.env b/mailserver.env index 6bc50e85..f7d69c9c 100644 --- a/mailserver.env +++ b/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=