From c461dabe9e5bb7e263169def89469f7c1c9d9dd5 Mon Sep 17 00:00:00 2001 From: Georg Lauterbach <44545919+georglauterbach@users.noreply.github.com> Date: Wed, 10 May 2023 11:02:44 +0200 Subject: [PATCH] docs/misc: update to align with Docker Compose v2 (#3295) * rename: `docker-compose.yml` => `compose.yaml` * rename: `docker-compose` => `docker compose` --- .github/ISSUE_TEMPLATE/bug_report.yml | 4 +-- docker-compose.yml => compose.yaml | 0 .../config/advanced/full-text-search.md | 20 ++++++------ docs/content/config/advanced/ipv6.md | 2 +- .../content/config/advanced/mail-fetchmail.md | 4 +-- docs/content/config/advanced/mail-sieve.md | 2 +- .../maintenance/update-and-cleanup.md | 4 +-- .../advanced/override-defaults/dovecot.md | 2 +- docs/content/config/advanced/podman.md | 20 ++++++------ .../config/best-practices/dkim_dmarc_spf.md | 2 +- docs/content/config/environment.md | 8 ++--- docs/content/config/pop3.md | 2 +- docs/content/config/security/fail2ban.md | 4 +-- docs/content/config/security/mail_crypt.md | 4 +-- docs/content/config/security/ssl.md | 32 +++++++++---------- .../examples/tutorials/basic-installation.md | 8 ++--- .../examples/use-cases/imap-folders.md | 6 ++-- docs/content/faq.md | 18 +++++------ docs/content/introduction.md | 5 ++- docs/content/usage.md | 11 ++++--- mailserver.env | 4 +-- target/scripts/helpers/ssl.sh | 4 +-- .../process_check_restart.bats | 2 +- 23 files changed, 84 insertions(+), 84 deletions(-) rename docker-compose.yml => compose.yaml (100%) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 55e8083c..e8d60dab 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -125,8 +125,8 @@ body: - type: textarea id: important-environment-variables attributes: - label: docker-compose.yml - description: Show us your `docker-compose.yml` file or your equivalent `docker run` command, if applicable. This filed is formatted as YAML. + label: compose.yaml + description: Show us your `compose.yaml` file or your equivalent `docker run` command, if applicable. This filed is formatted as YAML. render: yml - type: textarea id: relevant-log-output diff --git a/docker-compose.yml b/compose.yaml similarity index 100% rename from docker-compose.yml rename to compose.yaml diff --git a/docs/content/config/advanced/full-text-search.md b/docs/content/config/advanced/full-text-search.md index f4f2f760..2e29e496 100644 --- a/docs/content/config/advanced/full-text-search.md +++ b/docs/content/config/advanced/full-text-search.md @@ -55,7 +55,7 @@ While indexing is memory intensive, you can configure the plugin to limit the am adjust the settings to tune for your desired memory limits, exclude folders and enable searching text inside of attachments -2. Update `docker-compose.yml` to load the previously created dovecot plugin config file: +2. Update `compose.yaml` to load the previously created dovecot plugin config file: ```yaml services: @@ -86,20 +86,20 @@ While indexing is memory intensive, you can configure the plugin to limit the am 3. Recreate containers: ``` - docker-compose down - docker-compose up -d + docker compose down + docker compose up -d ``` 4. Initialize indexing on all users for all mail: ``` - docker-compose exec mailserver doveadm index -A -q \* + docker compose exec mailserver doveadm index -A -q \* ``` 5. Run the following command in a daily cron job: ``` - docker-compose exec mailserver doveadm fts optimize -A + docker compose exec mailserver doveadm fts optimize -A ``` Or like the [Spamassassin example][docs-faq-sa-learn-cron] shows, you can instead use `cron` from within DMS to avoid potential errors if the mail server is not running: @@ -108,7 +108,7 @@ While indexing is memory intensive, you can configure the plugin to limit the am Create a _system_ cron file: ```sh - # in the docker-compose.yml root directory + # in the compose.yaml root directory mkdir -p ./docker-data/dms/cron # if you didn't have this folder before touch ./docker-data/dms/cron/fts_xapian chown root:root ./docker-data/dms/cron/fts_xapian @@ -127,7 +127,7 @@ While indexing is memory intensive, you can configure the plugin to limit the am 0 4 * * * root doveadm fts optimize -A ``` - Then with `docker-compose.yml`: + Then with `compose.yaml`: ```yaml services: @@ -148,7 +148,7 @@ However, Solr also requires a fair bit of RAM. While Solr is [highly tuneable](h #### Setup -1. `docker-compose.yml`: +1. `compose.yaml`: ```yaml solr: @@ -180,9 +180,9 @@ However, Solr also requires a fair bit of RAM. While Solr is [highly tuneable](h } ``` -3. Recreate containers: `docker-compose down ; docker-compose up -d` +3. Recreate containers: `docker compose down ; docker compose up -d` -4. Flag all user mailbox FTS indexes as invalid, so they are rescanned on demand when they are next searched: `docker-compose exec mailserver doveadm fts rescan -A` +4. Flag all user mailbox FTS indexes as invalid, so they are rescanned on demand when they are next searched: `docker compose exec mailserver doveadm fts rescan -A` #### Further Discussion diff --git a/docs/content/config/advanced/ipv6.md b/docs/content/config/advanced/ipv6.md index 2853e434..d77f8d7a 100644 --- a/docs/content/config/advanced/ipv6.md +++ b/docs/content/config/advanced/ipv6.md @@ -11,7 +11,7 @@ This can be solved by supporting IPv6 connections all the way to the DMS contain ## Setup steps ```diff -+++ b/serv/docker-compose.yml ++++ b/serv/compose.yaml @@ ... @@ services: + ipv6nat: diff --git a/docs/content/config/advanced/mail-fetchmail.md b/docs/content/config/advanced/mail-fetchmail.md index b364eed0..59e07a84 100644 --- a/docs/content/config/advanced/mail-fetchmail.md +++ b/docs/content/config/advanced/mail-fetchmail.md @@ -2,7 +2,7 @@ title: 'Advanced | Email Gathering with Fetchmail' --- -To enable the [fetchmail][fetchmail-website] service to retrieve e-mails set the environment variable `ENABLE_FETCHMAIL` to `1`. Your `docker-compose.yml` file should look like following snippet: +To enable the [fetchmail][fetchmail-website] service to retrieve e-mails set the environment variable `ENABLE_FETCHMAIL` to `1`. Your `compose.yaml` file should look like following snippet: ```yaml environment: @@ -18,7 +18,7 @@ Generate a file called `fetchmail.cf` and place it in the `docker-data/dms/confi │   ├── fetchmail.cf │   ├── postfix-accounts.cf │   └── postfix-virtual.cf -├── docker-compose.yml +├── compose.yaml └── README.md ``` diff --git a/docs/content/config/advanced/mail-sieve.md b/docs/content/config/advanced/mail-sieve.md index f6577329..2918cdfe 100644 --- a/docs/content/config/advanced/mail-sieve.md +++ b/docs/content/config/advanced/mail-sieve.md @@ -85,7 +85,7 @@ The [Manage Sieve](https://doc.dovecot.org/admin_manual/pigeonhole_managesieve_s !!! example ```yaml - # docker-compose.yml + # compose.yaml ports: - "4190:4190" environment: diff --git a/docs/content/config/advanced/maintenance/update-and-cleanup.md b/docs/content/config/advanced/maintenance/update-and-cleanup.md index dcf53c93..3e4301f9 100644 --- a/docs/content/config/advanced/maintenance/update-and-cleanup.md +++ b/docs/content/config/advanced/maintenance/update-and-cleanup.md @@ -8,7 +8,7 @@ Docker images are handy but it can become a hassle to keep them updated. Also wh One could setup a complex action/hook-based workflow using probes, but there is a nice, easy to use docker image that solves this issue and could prove useful: [`watchtower`](https://hub.docker.com/r/containrrr/watchtower). -A docker-compose example: +A Docker Compose example: ```yaml services: @@ -25,7 +25,7 @@ For more details, see the [manual](https://containrrr.github.io/watchtower/) When you are pulling new images in automatically, it would be nice to have them cleaned up as well. There is also a docker image for this: [`spotify/docker-gc`](https://hub.docker.com/r/spotify/docker-gc/). -A docker-compose example: +A Docker Compose example: ```yaml services: diff --git a/docs/content/config/advanced/override-defaults/dovecot.md b/docs/content/config/advanced/override-defaults/dovecot.md index ab1f3bb5..84d13a04 100644 --- a/docs/content/config/advanced/override-defaults/dovecot.md +++ b/docs/content/config/advanced/override-defaults/dovecot.md @@ -14,7 +14,7 @@ Your DMS folder structure should look like this example: │ ├── dovecot.cf │ ├── postfix-accounts.cf │ └── postfix-virtual.cf -├── docker-compose.yml +├── compose.yaml └── README.md ``` diff --git a/docs/content/config/advanced/podman.md b/docs/content/config/advanced/podman.md index fb149f6e..b32288c1 100644 --- a/docs/content/config/advanced/podman.md +++ b/docs/content/config/advanced/podman.md @@ -23,7 +23,7 @@ Podman is a daemonless container engine for developing, managing, and running OC While using Podman, you can just manage docker-mailserver as what you did with Docker. Your best friend `setup.sh` includes the minimum code in order to support Podman since it's 100% compatible with the Docker CLI. -The installation is basically the same. Podman v3.2 introduced a RESTful API that is 100% compatible with the Docker API, so you can use docker-compose with Podman easily. Install Podman and docker-compose with your package manager first. +The installation is basically the same. Podman v3.2 introduced a RESTful API that is 100% compatible with the Docker API, so you can use Docker Compose with Podman easily. Install Podman and Docker Compose with your package manager first. ```bash sudo dnf install podman docker-compose @@ -39,8 +39,8 @@ This will create a unix socket locate under `/run/podman/podman.sock`, which is ```bash export DOCKER_HOST="unix:///run/podman/podman.sock" -docker-compose up -d mailserver -docker-compose ps +docker compose up -d mailserver +docker compose ps ``` You should see that docker-mailserver is running now. @@ -75,7 +75,7 @@ First, enable `podman.socket` in systemd's userspace with a non-root user. systemctl enable --now --user podman.socket ``` -The socket file should be located at `/var/run/user/$(id -u)/podman/podman.sock`. Then, modify `docker-compose.yml` to make sure all ports are bindings are on non-privileged ports. +The socket file should be located at `/var/run/user/$(id -u)/podman/podman.sock`. Then, modify `compose.yaml` to make sure all ports are bindings are on non-privileged ports. ```yaml services: @@ -88,12 +88,12 @@ services: - "10993:993" # IMAP4 (implicit TLS) ``` -Then, setup your `mailserver.env` file follow the documentation and use docker-compose to start the container. +Then, setup your `mailserver.env` file follow the documentation and use Docker Compose to start the container. ```bash export DOCKER_HOST="unix:///var/run/user/$(id -u)/podman/podman.sock" -docker-compose up -d mailserver -docker-compose ps +docker compose up -d mailserver +docker compose ps ``` ### Security in Rootless Mode @@ -106,12 +106,12 @@ The `PERMIT_DOCKER` variable in the `mailserver.env` file allows to specify trus #### Use the slip4netns network driver -The second workaround is slightly more complicated because the `docker-compose.yml` has to be modified. +The second workaround is slightly more complicated because the `compose.yaml` has to be modified. As shown in the [fail2ban section](../../security/fail2ban/#podman-with-slirp4netns-port-driver) the `slirp4netns` network driver has to be enabled. This network driver enables podman to correctly resolve IP addresses but it is not compatible with user defined networks which might be a problem depending on your setup. -[Rootless Podman][rootless::podman] requires adding the value `slirp4netns:port_handler=slirp4netns` to the `--network` CLI option, or `network_mode` setting in your `docker-compose.yml`. +[Rootless Podman][rootless::podman] requires adding the value `slirp4netns:port_handler=slirp4netns` to the `--network` CLI option, or `network_mode` setting in your `compose.yaml`. You must also add the ENV `NETWORK_INTERFACE=tap0`, because Podman uses a [hard-coded interface name][rootless::podman::interface] for `slirp4netns`. @@ -169,7 +169,7 @@ firewall-cmd --permanent --direct --add-rule nat OUTPUT 0 -p Uses the `hostname -f` command to get canonical hostname for DMS to use. - => Specify an FQDN (fully-qualified domain name) to serve mail for. The hostname is required for DMS to function correctly. @@ -132,7 +132,7 @@ Enabled `policyd-spf` in Postfix's configuration. You will likely want to set th - **0** => fail2ban service disabled - 1 => Enables fail2ban service -If you enable Fail2Ban, don't forget to add the following lines to your `docker-compose.yml`: +If you enable Fail2Ban, don't forget to add the following lines to your `compose.yaml`: ``` BASH cap_add: @@ -458,7 +458,7 @@ Changes the interval in which log files are rotated. The entire log output for the container is still available via `docker logs mailserver` (or your respective container name). If you want to configure external log rotation for that container output as well, : [Docker Logging Drivers](https://docs.docker.com/config/containers/logging/configure/). - By default, the logs are lost when the container is destroyed (eg: re-creating via `docker-compose down && docker-compose up -d`). To keep the logs, mount a volume (to `/var/log/mail/`). + By default, the logs are lost when the container is destroyed (eg: re-creating via `docker compose down && docker compose up -d`). To keep the logs, mount a volume (to `/var/log/mail/`). !!! note @@ -562,7 +562,7 @@ Deprecated. See [`ACCOUNT_PROVISIONER`](#account_provisioner). - **empty** => mail.example.com - => Specify the dns-name/ip-address where the ldap-server is listening, or an URI like `ldaps://mail.example.com` -- NOTE: If you going to use DMS in combination with `docker-compose.yml` you can set the service name here +- NOTE: If you going to use DMS in combination with `compose.yaml` you can set the service name here ##### LDAP_SEARCH_BASE diff --git a/docs/content/config/pop3.md b/docs/content/config/pop3.md index 1acc8e85..0cc9e17f 100644 --- a/docs/content/config/pop3.md +++ b/docs/content/config/pop3.md @@ -4,7 +4,7 @@ hide: - toc # Hide Table of Contents for this page --- -If you want to use POP3(S), you have to add the ports 110 and/or 995 (TLS secured) and the environment variable `ENABLE_POP3` to your `docker-compose.yml`: +If you want to use POP3(S), you have to add the ports 110 and/or 995 (TLS secured) and the environment variable `ENABLE_POP3` to your `compose.yaml`: ```yaml mailserver: diff --git a/docs/content/config/security/fail2ban.md b/docs/content/config/security/fail2ban.md index b9f8ad38..0ea052a1 100644 --- a/docs/content/config/security/fail2ban.md +++ b/docs/content/config/security/fail2ban.md @@ -16,7 +16,7 @@ hide: !!! warning - DMS must be launched with the `NET_ADMIN` capability in order to be able to install the NFTables rules that actually ban IP addresses. Thus, either include `--cap-add=NET_ADMIN` in the `docker run` command, or the equivalent in the `compose.yml`: + DMS must be launched with the `NET_ADMIN` capability in order to be able to install the NFTables rules that actually ban IP addresses. Thus, either include `--cap-add=NET_ADMIN` in the `docker run` command, or the equivalent in the `compose.yaml`: ```yaml cap_add: @@ -106,7 +106,7 @@ It is necessary for F2B to have access to the real source IP addresses in order === "Podman" - [Rootless Podman][rootless::podman] requires adding the value `slirp4netns:port_handler=slirp4netns` to the `--network` CLI option, or `network_mode` setting in your `compose.yml`: + [Rootless Podman][rootless::podman] requires adding the value `slirp4netns:port_handler=slirp4netns` to the `--network` CLI option, or `network_mode` setting in your `compose.yaml`: !!! example diff --git a/docs/content/config/security/mail_crypt.md b/docs/content/config/security/mail_crypt.md index 12f8698b..463e91f6 100644 --- a/docs/content/config/security/mail_crypt.md +++ b/docs/content/config/security/mail_crypt.md @@ -30,7 +30,7 @@ Official Dovecot documentation: https://doc.dovecot.org/configuration_manual/mai } ``` -2. Shutdown your mailserver (`docker-compose down`) +2. Shutdown your mailserver (`docker compose down`) 3. You then need to [generate your global EC key](https://doc.dovecot.org/configuration_manual/mail_crypt_plugin/#ec-key). We named them `/certs/ecprivkey.pem` and `/certs/ecpubkey.pem` in step #1. @@ -45,7 +45,7 @@ Official Dovecot documentation: https://doc.dovecot.org/configuration_manual/mai . . . ``` -5. While you're editing the `docker-compose.yml`, add the configuration file: +5. While you're editing the `compose.yaml`, add the configuration file: ```yaml services: mailserver: diff --git a/docs/content/config/security/ssl.md b/docs/content/config/security/ssl.md index 2df2056b..f81470ac 100644 --- a/docs/content/config/security/ssl.md +++ b/docs/content/config/security/ssl.md @@ -44,7 +44,7 @@ An [FQDN](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) (_Fully Qua or ```yml - # docker-compose.yml + # compose.yaml services: mailserver: hostname: mail.example.com @@ -72,7 +72,7 @@ You don't have to do anything else. Enjoy! !!! example - Add these additions to the `mailserver` service in your [`docker-compose.yml`][github-file-compose]: + Add these additions to the `mailserver` service in your [`compose.yaml`][github-file-compose]: ```yaml services: @@ -103,7 +103,7 @@ Certbot provisions certificates to `/etc/letsencrypt`. Add a volume to store the !!! example - Add these additions to the `mailserver` service in your [`docker-compose.yml`][github-file-compose]: + Add these additions to the `mailserver` service in your [`compose.yaml`][github-file-compose]: ```yaml services: @@ -163,7 +163,7 @@ Obtain a Cloudflare API token: - As this is sensitive data, you should restrict access to it with `chmod 600` and `chown 0:0`. - Store the file in a folder if you like, such as `docker-data/certbot/secrets/`. -5. Your `docker-compose.yml` should include the following: +5. Your `compose.yaml` should include the following: ```yaml services: @@ -206,7 +206,7 @@ Obtain a Cloudflare API token: 6. Run the service to provision a certificate: ```sh - docker-compose run certbot-cloudflare + docker compose run certbot-cloudflare ``` 7. You should see the following log output: @@ -229,7 +229,7 @@ After completing the steps above, your certificate should be ready to use. We've only demonstrated how to provision a certificate, but it will expire in 90 days and need to be renewed before then. - In the following example, add a new service (`certbot-cloudflare-renew`) into `docker-compose.yml` that will handle certificate renewals: + In the following example, add a new service (`certbot-cloudflare-renew`) into `compose.yaml` that will handle certificate renewals: ```yml services: @@ -247,7 +247,7 @@ After completing the steps above, your certificate should be ready to use. You can manually run this service to renew the cert within 90 days: ```sh - docker-compose run certbot-cloudflare-renew + docker compose run certbot-cloudflare-renew ``` You should see the following output @@ -273,7 +273,7 @@ After completing the steps above, your certificate should be ready to use. (`crontab` example: Checks every day if the certificate should be renewed) ```sh - 0 0 * * * docker-compose -f PATH_TO_YOUR_DOCKER_COMPOSE_YML up certbot-cloudflare-renew + 0 0 * * * docker compose -f PATH_TO_YOUR_DOCKER_COMPOSE_YML up certbot-cloudflare-renew ``` #### Example using `nginx-proxy` and `acme-companion` with Docker { data-toc-label='nginx-proxy with Docker' } @@ -327,7 +327,7 @@ In the following example, we show how DMS can be run alongside the docker contai You may want to add `--env LETSENCRYPT_TEST=true` to the above while testing, to avoid the _Let's Encrypt_ certificate generation rate limits. -5. Make sure your mount path to the `letsencrypt` certificates directory is correct. Edit your `docker-compose.yml` for the `mailserver` service to have volumes added like below: +5. Make sure your mount path to the `letsencrypt` certificates directory is correct. Edit your `compose.yaml` for the `mailserver` service to have volumes added like below: ```yaml volumes: @@ -337,15 +337,15 @@ In the following example, we show how DMS can be run alongside the docker contai - ./docker-data/acme-companion/certs/:/etc/letsencrypt/live/:ro ``` -6. Then from the `docker-compose.yml` project directory, run: `docker-compose up -d mailserver`. +6. Then from the `compose.yaml` project directory, run: `docker compose up -d mailserver`. #### Example using `nginx-proxy` and `acme-companion` with `docker-compose` { data-toc-label='nginx-proxy with docker-compose' } The following example is the [basic setup][acme-companion::basic-setup] you need for using `nginx-proxy` and `acme-companion` with DMS (_Referencing: [`acme-companion` documentation][acme-companion::docs]_): -???+ example "Example: `docker-compose.yml`" +???+ example "Example: `compose.yaml`" - You should have an existing `docker-compose.yml` with a `mailserver` service. Below are the modifications to add for integrating with `nginx-proxy` and `acme-companion` services: + You should have an existing `compose.yaml` with a `mailserver` service. Below are the modifications to add for integrating with `nginx-proxy` and `acme-companion` services: ```yaml services: @@ -385,7 +385,7 @@ The following example is the [basic setup][acme-companion::basic-setup] you need container_name: nginx-proxy-acme restart: always environment: - # Only docker-compose v2 supports: `volumes_from: [nginx-proxy]`, + # When `volumes_from: [nginx-proxy]` is not supported, # reference the _reverse-proxy_ `container_name` here: - NGINX_PROXY_CONTAINER=nginx-proxy volumes: @@ -463,7 +463,7 @@ Version 6.2 and later of the Synology NAS DSM OS now come with an interface to g Amongst other things, you can use these to secure your mail server. DSM locates the generated certificates in a folder below `/usr/syno/etc/certificate/_archive/`. -Navigate to that folder and note the 6 character random folder name of the certificate you'd like to use. Then, add the following to your `docker-compose.yml` declaration file: +Navigate to that folder and note the 6 character random folder name of the certificate you'd like to use. Then, add the following to your `compose.yaml` declaration file: ```yaml volumes: @@ -689,7 +689,7 @@ docker run --rm -it \ ### Bring Your Own Certificates -You can also provide your own certificate files. Add these entries to your `docker-compose.yml`: +You can also provide your own certificate files. Add these entries to your `compose.yaml`: ```yaml volumes: @@ -878,7 +878,7 @@ Despite this, if you must use non-standard DH parameters or you would like to sw [docs-optional-config]: ../advanced/optional-config.md [docs-faq-baredomain]: ../../faq.md#can-i-use-a-nakedbare-domain-ie-no-hostname -[github-file-compose]: https://github.com/docker-mailserver/docker-mailserver/blob/master/docker-compose.yml +[github-file-compose]: https://github.com/docker-mailserver/docker-mailserver/blob/master/compose.yaml [github-file::tls-readme]: https://github.com/docker-mailserver/docker-mailserver/blob/3b8059f2daca80d967635e04d8d81e9abb755a4d/test/test-files/ssl/example.test/README.md [hanscees-renewcerts]: https://github.com/hanscees/dockerscripts/blob/master/scripts/tomav-renew-certs diff --git a/docs/content/examples/tutorials/basic-installation.md b/docs/content/examples/tutorials/basic-installation.md index 01b8d5ae..2ad4982e 100644 --- a/docs/content/examples/tutorials/basic-installation.md +++ b/docs/content/examples/tutorials/basic-installation.md @@ -4,7 +4,7 @@ title: 'Tutorials | Basic Installation' ## A Basic Example With Relevant Environmental Variables -This example provides you only with a basic example of what a minimal setup could look like. We **strongly recommend** that you go through the configuration file yourself and adjust everything to your needs. The default [docker-compose.yml](https://github.com/docker-mailserver/docker-mailserver/blob/master/docker-compose.yml) can be used for the purpose out-of-the-box, see the [_Usage_ chapter](../../usage.md). +This example provides you only with a basic example of what a minimal setup could look like. We **strongly recommend** that you go through the configuration file yourself and adjust everything to your needs. The default [compose.yaml](https://github.com/docker-mailserver/docker-mailserver/blob/master/compose.yaml) can be used for the purpose out-of-the-box, see the [_Usage_ chapter](../../usage.md). ``` YAML services: @@ -96,7 +96,7 @@ In this setup DMS is not intended to receive email from the outside world, so no Adding the docker network's gateway to the list of trusted hosts (_eg: 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][github-issue-1405-comment]. -1. Create the file `docker-compose.yml` with a content like this: +1. Create the file `compose.yaml` with a content like this: !!! example @@ -182,7 +182,7 @@ In this setup DMS is not intended to receive email from the outside world, so no 4. Get an SSL certificate, [we have a guide for you here][docs-ssl] (_Let's Encrypt_ is a popular service to get free SSL certificates). -5. Start DMS and check the terminal output for any errors: `docker-compose up`. +5. Start DMS and check the terminal output for any errors: `docker compose up`. 6. Create email accounts and aliases: @@ -214,7 +214,7 @@ In this setup DMS is not intended to receive email from the outside world, so no This extra step is required to avoid the `553 5.7.1 Sender address rejected: not owned by user` error (_the accounts used for submitting mail to Gmail are `admin.gmail@example.com` and `info.gmail@example.com`_) -7. Send some test emails to these addresses and make other tests. Once everything is working well, stop the container with `ctrl+c` and start it again as a daemon: `docker-compose up -d`. +7. Send some test emails to these addresses and make other tests. Once everything is working well, stop the container with `ctrl+c` and start it again as a daemon: `docker compose up -d`. [docs-ports]: ../../config/security/understanding-the-ports.md [docs-environment]: ../../config/environment.md diff --git a/docs/content/examples/use-cases/imap-folders.md b/docs/content/examples/use-cases/imap-folders.md index 1d1b2539..ad5f3ed3 100644 --- a/docs/content/examples/use-cases/imap-folders.md +++ b/docs/content/examples/use-cases/imap-folders.md @@ -16,7 +16,7 @@ See [`target/dovecot/15-mailboxes.conf`][github-config-dovecot-mailboxes] for ex The `Archive` special IMAP folder may be useful to enable. To do so, make a copy of [`target/dovecot/15-mailboxes.conf`][github-config-dovecot-mailboxes] and uncomment the `Archive` mailbox definition. Mail clients should understand that this folder is intended for archiving mail due to the [`\Archive` _"SPECIAL-USE"_ attribute][rfc-6154]. -With the provided [docker-compose.yml][github-config-dockercompose] example, a volume bind mounts the host directory `docker-data/dms/config/` to the container location `/tmp/docker-mailserver/`. Config file overrides should instead be mounted to a different location as described in [Overriding Configuration for Dovecot][docs-config-overrides-dovecot]: +With the provided [compose.yaml][github-config-dockercompose] example, a volume bind mounts the host directory `docker-data/dms/config/` to the container location `/tmp/docker-mailserver/`. Config file overrides should instead be mounted to a different location as described in [Overriding Configuration for Dovecot][docs-config-overrides-dovecot]: ```yaml volumes: @@ -60,12 +60,12 @@ Take care to test localized names work well as well. !!! note "Needs citation" This information is provided by the community. - + It presently lacks references to confirm the behaviour. If any information is incorrect please let us know! :smile: [docs-config-overrides-dovecot]: ../../config/advanced/override-defaults/dovecot.md#override-configuration -[github-config-dockercompose]: https://github.com/docker-mailserver/docker-mailserver/blob/master/docker-compose.yml +[github-config-dockercompose]: https://github.com/docker-mailserver/docker-mailserver/blob/master/compose.yaml [github-config-dovecot-mailboxes]: https://github.com/docker-mailserver/docker-mailserver/blob/master/target/dovecot/15-mailboxes.conf [dovecot-docs-namespaces]: https://doc.dovecot.org/configuration_manual/namespace/#namespace-inbox [dovecot-docs-mailboxes]: https://doc.dovecot.org/configuration_manual/namespace/#mailbox-settings diff --git a/docs/content/faq.md b/docs/content/faq.md index 7c28b0bd..dd313631 100644 --- a/docs/content/faq.md +++ b/docs/content/faq.md @@ -21,9 +21,9 @@ Mails are stored in `/var/mail/${domain}/${username}`. Since `v9.0.0` it is poss Then, run the following commands: ``` BASH -docker-compose pull -docker-compose down -docker-compose up -d +docker compose pull +docker compose down +docker compose up -d ``` You should see the new version number on startup, for example: `[ INF ] Welcome to docker-mailserver 11.3.1`. And you're done! Don't forget to have a look at the remaining functions of the `setup.sh` script with `./setup.sh help`. @@ -97,7 +97,7 @@ DMS supports multiple domains out of the box, so you can do this: #### Bind mounts (default) -From the location of your `docker-compose.yml`, create a compressed archive of your `docker-data/dms/config/` and `docker-data/dms/mail-*` folders: +From the location of your `compose.yaml`, create a compressed archive of your `docker-data/dms/config/` and `docker-data/dms/mail-*` folders: ```bash tar --gzip -cf "backup-$(date +%F).tar.gz" ./docker-data/dms @@ -167,7 +167,7 @@ warning: do not list domain example.com in BOTH mydestination and virtual_mailbo Plus of course mail delivery fails. -Also you need to define `hostname: example.com` in your `docker-compose.yml`. +Also you need to define `hostname: example.com` in your `compose.yaml`. !!! tip "You might not want a bare domain" @@ -281,7 +281,7 @@ Suppose you want to change a number of settings that are not listed as variables DMS has a built-in way to do post-install processes. If you place a script called **`user-patches.sh`** in the config directory it will be run after all configuration files are set up, but before the postfix, amavis and other daemons are started. -It is common to use a local directory for config added to `docker-mailsever` via a volume mount in your `docker-compose.yml` (eg: `./docker-data/dms/config/:/tmp/docker-mailserver/`). +It is common to use a local directory for config added to `docker-mailsever` via a volume mount in your `compose.yaml` (eg: `./docker-data/dms/config/:/tmp/docker-mailserver/`). Add or create the script file to your config directory: @@ -376,7 +376,7 @@ Antispam rules are managed in `docker-data/dms/config/spamassassin-rules.cf`. For no subject set `SA_SPAM_SUBJECT=undef`. -For a trailing white-space subject one can define the whole variable with quotes in `docker-compose.yml`: +For a trailing white-space subject one can define the whole variable with quotes in `compose.yaml`: ```yaml environment: @@ -411,7 +411,7 @@ The following configuration works nicely: Create a _system_ cron file: ```sh - # in the docker-compose.yml root directory + # in the compose.yaml root directory mkdir -p ./docker-data/dms/cron touch ./docker-data/dms/cron/sa-learn chown root:root ./docker-data/dms/cron/sa-learn @@ -445,7 +445,7 @@ The following configuration works nicely: 30 3 * * * root sa-learn --ham /var/mail/not-example.com/*/cur* --dbpath /var/mail-state/lib-amavis/.spamassassin > /dev/null ``` - Then with `docker-compose.yml`: + Then with `compose.yaml`: ```yaml services: diff --git a/docs/content/introduction.md b/docs/content/introduction.md index a92a86d9..73c7e58c 100644 --- a/docs/content/introduction.md +++ b/docs/content/introduction.md @@ -204,14 +204,13 @@ The best practice as of 2020 would be [POP3S][wikipedia-pop3s] on port 995, rath As a _batteries included_ container image, DMS provides you with all the required components and a default configuration to run a decent and secure mail server. One may then customize all aspects of its internal components. -- Simple customization is supported through [docker-compose configuration][github-file-compose] and the [env-mailserver][github-file-envmailserver] configuration file. +- Simple customization is supported through [Docker Compose configuration][github-file-compose] and the [env-mailserver][github-file-envmailserver] configuration file. - Advanced customization is supported through providing "monkey-patching" configuration files and/or [deriving your own image][github-file-dockerfile] from DMS's upstream, for a complete control over how things run. - Eventually, it is up to _you_ deciding exactly what kind of transportation/encryption to use and/or enforce, and to customize your instance accordingly (with looser or stricter security). Be also aware that protocols and ports on your server can only go so far with security; third-party MTAs might relay your emails on insecure connections, man-in-the-middle attacks might still prove effective, etc. Advanced counter-measure such as DANE, MTA-STS and/or full body encryption (eg. PGP) should be considered as well for increased confidentiality, but ideally without compromising backwards compatibility so as to not block emails. [docs-understandports]: ./config/security/understanding-the-ports.md -[github-file-compose]: https://github.com/docker-mailserver/docker-mailserver/blob/master/docker-compose.yml +[github-file-compose]: https://github.com/docker-mailserver/docker-mailserver/blob/master/compose.yaml [github-file-envmailserver]: https://github.com/docker-mailserver/docker-mailserver/blob/master/mailserver.env [github-file-dockerfile]: https://github.com/docker-mailserver/docker-mailserver/blob/master/Dockerfile [rfc-2487]: https://tools.ietf.org/html/rfc2487 diff --git a/docs/content/usage.md b/docs/content/usage.md index bf656b52..0ea8beaf 100644 --- a/docs/content/usage.md +++ b/docs/content/usage.md @@ -21,16 +21,17 @@ There are a few requirements for a suitable host system: 2. The host should be able to send/receive on the [necessary ports for mail][docs-ports-overview] 3. You should be able to set a `PTR` record for your host; security-hardened mail servers might otherwise reject your mail server as the IP address of your host does not resolve correctly/at all to the DNS name of your server. -On the host, you should have a suitable container runtime (like _Docker_ or _Podman_) installed. We assume [_Docker Compose_][docker-compose] is [installed][docker-compose-installation]. +!!! note "About the Container Runtime" -!!! info "Podman Support" + On the host, you need to have a suitable container runtime (like _Docker_ or _Podman_) installed. We assume [_Docker Compose_][docker-compose] is [installed][docker-compose-installation]. We have aligned file names and configuration conventions with the latest [Docker Compose (currently V2) specification][docker-compose-specification]. If you're using podman, make sure to read the related [documentation][docs-podman]. -[docs-podman]: ./config/advanced/podman.md [docs-ports-overview]: ./config/security/understanding-the-ports.md#overview-of-email-ports [docker-compose]: https://docs.docker.com/compose/ [docker-compose-installation]: https://docs.docker.com/compose/install/ +[docker-compose-specification]: https://docs.docker.com/compose/compose-file/ +[docs-podman]: ./config/advanced/podman.md ### Minimal DNS Setup @@ -88,13 +89,13 @@ Issue the following commands to acquire the necessary files: ``` BASH DMS_GITHUB_URL="https://github.com/docker-mailserver/docker-mailserver/blob/latest" -wget "${DMS_GITHUB_URL}/docker-compose.yml" +wget "${DMS_GITHUB_URL}/compose.yaml" wget "${DMS_GITHUB_URL}/mailserver.env" ``` ### Configuration Steps -1. First edit `docker-compose.yml` to your liking +1. First edit `compose.yaml` to your liking - Substitute `mail.example.com` according to your FQDN. - If you want to use SELinux for the `./docker-data/dms/config/:/tmp/docker-mailserver/` mount, append `-z` or `-Z`. 2. Then configure the environment specific to the mail server by editing [`mailserver.env`][docs-environment], but keep in mind that: diff --git a/mailserver.env b/mailserver.env index 7ff2843f..91ffbd15 100644 --- a/mailserver.env +++ b/mailserver.env @@ -178,7 +178,7 @@ AMAVIS_LOGLEVEL=0 # 1 => DNS block lists are enabled ENABLE_DNSBL=0 -# If you enable Fail2Ban, don't forget to add the following lines to your `docker-compose.yml`: +# If you enable Fail2Ban, don't forget to add the following lines to your `compose.yaml`: # cap_add: # - NET_ADMIN # Otherwise, `nftables` won't be able to ban IPs. @@ -397,7 +397,7 @@ ENABLE_LDAP= # yes => LDAP over TLS enabled for Postfix LDAP_START_TLS= -# If you going to use the mailserver in combination with docker-compose you can set the service name here +# If you going to use the mailserver in combination with Docker Compose you can set the service name here # empty => mail.domain.com # Specify the dns-name/ip-address where the ldap-server LDAP_SERVER_HOST= diff --git a/target/scripts/helpers/ssl.sh b/target/scripts/helpers/ssl.sh index 94d5dc59..f837be00 100644 --- a/target/scripts/helpers/ssl.sh +++ b/target/scripts/helpers/ssl.sh @@ -77,13 +77,13 @@ function _setup_ssl # Postfix configuration # NOTE: This operation doesn't replace the line, it appends to the end of the line. # Thus this method should only be used when this line has explicitly been replaced earlier in the script. - # Otherwise without `docker-compose down` first, a `docker-compose up` may + # Otherwise without `docker compose down` first, a `docker compose up` may # persist previous container state and cause a failure in postfix configuration. sedfile -i "s|^smtpd_tls_chain_files =.*|& ${PRIVATE_KEY_ALT} ${CERT_CHAIN_ALT}|" "${POSTFIX_CONFIG_MAIN}" # Dovecot configuration # Conditionally checks for `#`, in the event that internal container state is accidentally persisted, - # can be caused by: `docker-compose up` run again after a `ctrl+c`, without running `docker-compose down` + # can be caused by: `docker compose up` run again after a `ctrl+c`, without running `docker compose down` sedfile -i -r \ -e "s|^#?(ssl_alt_key =).*|\1 <${PRIVATE_KEY_ALT}|" \ -e "s|^#?(ssl_alt_cert =).*|\1 <${CERT_CHAIN_ALT}|" \ diff --git a/test/tests/parallel/set3/container_configuration/process_check_restart.bats b/test/tests/parallel/set3/container_configuration/process_check_restart.bats index 6a743bf8..b3d4fc86 100644 --- a/test/tests/parallel/set3/container_configuration/process_check_restart.bats +++ b/test/tests/parallel/set3/container_configuration/process_check_restart.bats @@ -197,7 +197,7 @@ function _check_if_process_is_running() { # The process manager (supervisord) should perform a graceful shutdown: # NOTE: Time limit should never be below these configured values: # - supervisor-app.conf:stopwaitsecs -# - docker-compose.yml:stop_grace_period +# - compose.yaml:stop_grace_period function _should_stop_cleanly() { run docker stop -t 60 "${CONTAINER_NAME}" assert_success