`README.md` and Documentation Update (#2389)
* follow up on #2383 Fixes a documentation error by which a list would not be rendered correctly. This has been taken care of. * update the `README.md` I felt the need to update the README for several reasons: 1. LDAP issues that the core maintainers team cannot really resolve 2. Cleaning up the somewhat messy structure near the end The first point goes without explanantion. The second points includes: 2.1. The tagging convention is now easier to read and understand 2.2. Some bullut points or notes have been inlined to "stick" more to the content that it actually belongs to 2.3. The note about the "old" `setup.sh` for DMS `10.1.0` has been removed as it is obsolete now. We encourage users to upgrade to `10.4.0` anyways. 2.4. The markdown code highlighting is now using `CONSOLE` instead of `BASH` because `CONSOLE` is more appropriate. 2.5. Capitalized headings 2.6. Updated the section about `./setup.sh help` to be in one place now instead of two 2.7. DKIM key generation does now not interfere with user account creation. * adjusted content to PR suggestions
This commit is contained in:
Georg Lauterbach
GitHub
parent
a7ad065f73
commit
4cb617f7f9
79
README.md
79
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 <CONTAINER NAME> setup <COMMAND>` 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 <CONTAINER NAME> setup <COMMAND>` 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 `<VERSION>` with the `docker-mailserver` release version you're using: `wget https://raw.githubusercontent.com/docker-mailserver/docker-mailserver/<VERSION>/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@<domain> <user@domain>
|
||||
```
|
||||
|
||||
### 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 '<domain.tld>[,<domain2.tld>]'
|
||||
```
|
||||
|
||||
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'
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
Loading…
Reference in New Issue