diff --git a/README.md b/README.md index 35e18f06..379aea8c 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ If you have issues, read the full `README` **and** the [documentation][documenta - [LetsEncrypt](https://letsencrypt.org/) and self-signed certificates - [Setup script](https://docker-mailserver.github.io/docker-mailserver/edge/config/setup.sh) to easily configure and maintain your mail-server - Basic [Sieve support](https://docker-mailserver.github.io/docker-mailserver/edge/config/advanced/mail-sieve) using dovecot -- SASLauthd with LDAP auth +- SASLauthd with LDAP auth (please see the note [down below](#ldap-setup)) - Persistent data and state - [CI/CD](https://github.com/docker-mailserver/docker-mailserver/actions) - [Extension Delimiters](http://www.postfix.org/postconf.5.html#recipient_delimiter) (`you+extension@example.com` go to `you@example.com`) @@ -55,8 +55,7 @@ If you have issues, read the full `README` **and** the [documentation][documenta - 1 vCore - 512MB RAM - -**Note:** You'll need to deactivate some services like ClamAV to be able to run on a host with 512MB of RAM. Even with 1G RAM you may run into problems without swap, see [FAQ](https://docker-mailserver.github.io/docker-mailserver/edge/faq/#what-system-requirements-are-required-to-run-docker-mailserver-effectively). +- You'll need to deactivate some services like ClamAV to be able to run on a host with 512MB of RAM. Even with 1G RAM you may run into problems without swap, see [FAQ](https://docker-mailserver.github.io/docker-mailserver/edge/faq/#what-system-requirements-are-required-to-run-docker-mailserver-effectively). ## Usage @@ -64,39 +63,29 @@ If you have issues, read the full `README` **and** the [documentation][documenta [CI/CD](https://github.com/docker-mailserver/docker-mailserver/actions) will automatically build, test and push new images to container registries. Currently, the following registries are supported: -- [DockerHub](https://hub.docker.com/r/mailserver/docker-mailserver) -- [GitHub Container Registry](https://github.com/orgs/docker-mailserver/packages?repo_name=docker-mailserver) +1. [DockerHub](https://hub.docker.com/r/mailserver/docker-mailserver) +2. [GitHub Container Registry](https://github.com/orgs/docker-mailserver/packages?repo_name=docker-mailserver) All workflows are using the tagging convention listed below. It is subsequently applied to all images. -| Event | Ref | Image Tags | -|--------------|-----------------------|-------------------------------| -| `push` | `refs/heads/master` | `edge` | -| `push tag` | `refs/tags/[v]1.2.3` | `1.2.3`, `1.2`, `1`, `latest` | +| Event | Image Tags | +|--------------------|-------------------------------| +| `push` on `master` | `edge` | +| `push tag` | `1.2.3`, `1.2`, `1`, `latest` | -### Get the tools +### Get the Tools -Since Docker Mailserver `v10.2.0`, `setup.sh` functionality is included within the Docker image. The external convenience script is no longer required if you prefer using `docker exec setup ` instead. - -**Note:** If you're using Docker or Docker Compose and are new to `docker-mailserver`, it is recommended to use the script `setup.sh` for convenience. +Since Docker Mailserver `v10.2.0`, **`setup.sh` functionality is included within the container image**. The external convenience script is no longer required if you prefer using `docker exec setup ` instead. **If you're new to `docker-mailserver`**, it is recommended to use the script `setup.sh` for convenience. ``` BASH DMS_GITHUB_URL='https://raw.githubusercontent.com/docker-mailserver/docker-mailserver/master' wget "${DMS_GITHUB_URL}/docker-compose.yml" wget "${DMS_GITHUB_URL}/mailserver.env" wget "${DMS_GITHUB_URL}/setup.sh" - chmod a+x ./setup.sh -./setup.sh help ``` -If no `docker-mailserver` container is running, any `./setup.sh` command will check online for the `:latest` image tag (the current stable release), performing a `pull` if necessary followed by running the command in a temporary container. - -#### `setup.sh` for `docker-mailserver` version `v10.1.x` and below - -If you're using `docker-mailserver` version `v10.1.x` or below, you will need to get `setup.sh` with a specific version. Substitute `` with the `docker-mailserver` release version you're using: `wget https://raw.githubusercontent.com/docker-mailserver/docker-mailserver//setup.sh`. - -### Create a docker-compose environment +### Create a docker-compose Environment 1. [Install the latest docker-compose](https://docs.docker.com/compose/install/) 2. Edit `docker-compose.yml` to your liking @@ -117,6 +106,25 @@ You are able to get a full overview of how the configuration works by either run 1. `./setup.sh help` which includes the options of `setup.sh`. 2. `docker run --rm docker.io/mailserver/docker-mailserver:latest setup help` which provides you with all the information on configuration provided "inside" the container itself. +If no `docker-mailserver` container is running, any `./setup.sh` command will check online for the `:latest` image tag (the current _stable_ release), performing a `docker pull ...` if necessary followed by running the command in a temporary container. + +``` CONSOLE +$ ./setup.sh help +Image 'docker.io/mailserver/docker-mailserver:latest' not found. Pulling ... +SETUP(1) + +NAME + setup - 'docker-mailserver' Administration & Configuration script +... + +$ docker run --rm docker.io/mailserver/docker-mailserver:latest setup help +SETUP(1) + +NAME + setup - 'docker-mailserver' Administration & Configuration script +... +``` + #### Starting for the first time On first start, you will likely see an error stating that there are no mail accounts and the container will exit. You must now do one of two things: @@ -135,21 +143,30 @@ docker-compose up -d mailserver # and configure aliases, DKIM and more ./setup.sh [-Z] alias add postmaster@ +``` + +### Miscellaneous + +#### DNS - DKIM + +You can (and you should) generate DKIM keys by running + +``` BASH ./setup.sh [-Z] config dkim ``` +If you want to see detailed usage information, run + +``` BASH +./setup.sh config dkim help +``` + In case you're using LDAP, the setup looks a bit different as you do not add user accounts directly. Postfix doesn't know your domain(s) and you need to provide it when configuring DKIM: ``` BASH ./setup.sh config dkim domain '[,]' ``` -If you want to see detailed usage information, run `./setup.sh config dkim help`. - -### Miscellaneous - -#### DNS - DKIM - When keys are generated, you can configure your DNS server by just pasting the content of `config/opendkim/keys/domain.tld/mail.txt` to [set up DKIM](https://mxtoolbox.com/dmarc/dkim/setup/how-to-setup-dkim). See the [documentation](https://docker-mailserver.github.io/docker-mailserver/edge/config/best-practices/dkim/) for more details. #### Custom User Changes & Patches @@ -158,7 +175,7 @@ If you'd like to change, patch or alter files or behavior of `docker-mailserver` #### Updating `docker-mailserver` -Make sure to read the [CHANGELOG](https://github.com/docker-mailserver/docker-mailserver/blob/master/CHANGELOG.md) before updating to new versions, to be prepared for possible breaking changes. +**Make sure to read the [CHANGELOG](https://github.com/docker-mailserver/docker-mailserver/blob/master/CHANGELOG.md)** before updating to new versions, to be prepared for possible breaking changes. ``` BASH docker-compose pull @@ -243,7 +260,9 @@ services: restart: always ``` -#### LDAP setup +### LDAP Setup + +**Note** There are currently no LDAP maintainers. If you encounter issues, please raise them in the issue tracker, but be aware that the core maintainers team will most likely not be able to help you. **We would appreciate and we encourage everyone to actively participate in maintaining LDAP-related code by becoming a maintainer!** ``` YAML version: '3.8' diff --git a/docs/content/config/security/ssl.md b/docs/content/config/security/ssl.md index 52f87346..a3823c86 100644 --- a/docs/content/config/security/ssl.md +++ b/docs/content/config/security/ssl.md @@ -102,8 +102,7 @@ You don't have to do anything else. Enjoy! #### Example using Docker for _Let's Encrypt_ { data-toc-label='Certbot with Docker' } -- Certbot provisions certificates to `/etc/letsencrypt`. Add a volume to store these, so that they can later be accessed by `docker-mailserver` container. -- You may also want to persist Certbot [logs][certbot::log-rotation], just in case you need to troubleshoot. +Certbot provisions certificates to `/etc/letsencrypt`. Add a volume to store these, so that they can later be accessed by `docker-mailserver` container. You may also want to persist Certbot [logs][certbot::log-rotation], just in case you need to troubleshoot. 1. Getting a certificate is this simple! (_Referencing: [Certbot docker instructions][certbot::docker] and [`certonly --standalone` mode][certbot::standalone]_): @@ -119,22 +118,22 @@ You don't have to do anything else. Enjoy! 2. Add a volume for `docker-mailserver` that maps the _local `certbot/certs/` folder_ to the container path `/etc/letsencrypt/`. -!!! example + !!! example - Add these additions to the `mailserver` service in your [`docker-compose.yml`][github-file-compose]: - - ```yaml - services: - mailserver: - # For the FQDN 'mail.example.com': - hostname: mail - domainname: example.com - environment: - - SSL_TYPE=letsencrypt - volumes: - - ./docker-data/certbot/certs/:/etc/letsencrypt - ``` + Add these additions to the `mailserver` service in your [`docker-compose.yml`][github-file-compose]: + ```yaml + services: + mailserver: + # For the FQDN 'mail.example.com': + hostname: mail + domainname: example.com + environment: + - SSL_TYPE=letsencrypt + volumes: + - ./docker-data/certbot/certs/:/etc/letsencrypt + ``` + 3. The certificate setup is complete, but remember _it will expire_. Consider automating renewals. !!! tip "Renewing Certificates"