Skip to content

Commit a88778f

Browse files
update README.md, looking for maintainers
1 parent a6bce57 commit a88778f

1 file changed

Lines changed: 33 additions & 71 deletions

File tree

README.md

Lines changed: 33 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -1,51 +1,26 @@
1-
# Docker-mailserver
1+
# K8s Helm Chart for Docker Mailserver
22

3-
[Docker-mailserver ](https://github.com/tomav/docker-mailserver)is fullstack but simple mailserver (smtp, imap, antispam, antivirus, ssl...) using Docker. See the author's motivations for creating it, [here](https://tvi.al/simple-mail-server-with-docker/).
3+
[Docker Mailserver](https://github.com/docker-mailserver/docker-mailserver) is a production-ready fullstack but simple mail server (SMTP, IMAP, LDAP, Antispam, Antivirus, etc.). Only configuration files, no SQL database. Keep it simple and versioned. Easy to deploy and upgrade. Documentation via MkDocs. Why this image was created.
44

5-
While the stack is intended to be run with Docker or Docker Compose, it's been adapted to [Docker Swarm](https://geek-cookbook.funkypenguin.co.nz/recipes/mail/), and to [Kubernetes](https://github.com/tomav/docker-mailserver/wiki/Using-in-Kubernetes).
5+
While the stack is intended to be run with Docker or Docker Compose, it's been [adapted to Kubernetes](https://github.com/docker-mailserver/docker-mailserver/wiki/Using-in-Kubernetes).
6+
7+
**_LOOKING FOR MAINTAINERS_**! This repository is looking for maintainers that keep the image version up to date and curate the chart. The chart is currently outdated with regards to the image itself as well as documentation and other, related topics. If you are using this Chart, it would be of much help if you provide a solution for issues you encountred in the form of a pull request.
68

79
## Introduction
810

9-
This helm chart deploys docker-mailserver into a Kubernetes cluster, in a manner which retains compatibility with the upstream, docker-specific version.
10-
11-
## Contents
12-
13-
- [Docker-mailserver](#docker-mailserver)
14-
- [Introduction](#introduction)
15-
- [Contents](#contents)
16-
- [Features](#features)
17-
- [Prerequisites](#prerequisites)
18-
- [Architecture](#architecture)
19-
- [Installation](#installation)
20-
- [Install helm and cert-manager](#install-helm-and-cert-manager)
21-
- [Installation](#installation-1)
22-
- [Operation](#operation)
23-
- [Download setup.sh](#download-setupsh)
24-
- [Create / Update / Delete users](#create--update--delete-users)
25-
- [Setup OpenDKIM](#setup-opendkim)
26-
- [Setup RainLoop](#setup-rainloop)
27-
- [Configuration](#configuration)
28-
- [Minimal configuration](#minimal-configuration)
29-
- [Chart Configuration](#chart-configuration)
30-
- [docker-mailserver Configuration](#docker-mailserver-configuration)
31-
- [Rainloop Configuration](#rainloop-configuration)
32-
- [HA Proxy-Ingress Configuration](#ha-proxy-ingress-configuration)
33-
- [Development](#development)
34-
- [Testing](#testing)
35-
36-
(Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc.go))
37-
38-
## Features
11+
This helm chart deploys docker-mailserver into a Kubernetes cluster, in a manner which retains compatibility with the upstream, docker-specific version.
12+
13+
## Features
3914

4015
The chart includes the following features:
4116

42-
* All configuration is done in values.yaml, or using the native "setup.sh" script (to create mailboxes or DKIM keys)
43-
* Avoids the [common problem of masking of source IP](https://kubernetes.io/docs/tutorials/services/source-ip/) by supporting haproxy's PROXY protocol (enabled by default)
44-
* Employs [cert-manager](https://github.com/jetstack/cert-manager) to automatically provide/renew SSL certificates
45-
* Bundles in [RainLoop](https://www.rainloop.net) for webmail access (disabled by default)
46-
* Starts in "demo" mode, allowing the user to test core functionality before configuring for specific domains
47-
* CI/CD tested against Kubernetes 1.18,1.19, and 1.20 : ![Lint and Test Charts](https://github.com/funkypenguin/helm-docker-mailserver/workflows/Lint%20and%20Test%20Charts/badge.svg)
48-
*
17+
- All configuration is done in values.yaml, or using the native "setup.sh" script (to create mailboxes or DKIM keys)
18+
- Avoids the [common problem of masking of source IP](https://kubernetes.io/docs/tutorials/services/source-ip/) by supporting haproxy's PROXY protocol (enabled by default)
19+
- Employs [cert-manager](https://github.com/jetstack/cert-manager) to automatically provide/renew SSL certificates
20+
- Bundles in [RainLoop](https://www.rainloop.net) for webmail access (disabled by default)
21+
- Starts in "demo" mode, allowing the user to test core functionality before configuring for specific domains
22+
- CI/CD tested against Kubernetes 1.18,1.19, and 1.20 : ![Lint and Test Charts](https://github.com/funkypenguin/helm-docker-mailserver/workflows/Lint%20and%20Test%20Charts/badge.svg)
23+
4924
## Prerequisites
5025

5126
- Kubernetes 1.16+ (*CI validates against > 1.18.0*)
@@ -55,11 +30,11 @@ external load balancer (e.g. AWS, DO or GKE). (There is an [update planned](http
5530
- __Suggested:__ PV provisioner support in the underlying infrastructure
5631
- [Cert-manager](https://github.com/jetstack/cert-manager/tree/master/deploy/charts/cert-manager) requires manual deployment into your cluster (details below)
5732
- [Helm](https://helm.sh) >= 2.13.0 (*errors were encountered when testing with 2.11.0, so the chart has a minimum requirement of 2.13.0*)
58-
- Access to a platform with Docker installed, in order to run [docker-mailserver's setup.sh binary](https://github.com/tomav/docker-mailserver/blob/master/setup.sh), which uses a docker container to setup dovecot password hashes and OpenDKIM keys
33+
- Access to a platform with Docker installed, in order to run [docker-mailserver's setup.sh binary](https://github.com/docker-mailserver/docker-mailserver/blob/master/setup.sh), which uses a docker container to setup dovecot password hashes and OpenDKIM keys
5934

6035
## Architecture
6136

62-
There are several ways you might deploy docker-mailserver. The most common would be:
37+
There are several ways you might deploy `docker-mailserver`. The most common would be:
6338

6439
1. Within a cloud provider, utilizing a load balancer service from the cloud provider (i.e. GKE). This is an expensive option, since typically you'd pay for each individual port (25, 465, 993, etc) which gets load-balanced
6540

@@ -71,11 +46,11 @@ There are several ways you might deploy docker-mailserver. The most common would
7146

7247
1. You need helm, obviously.
7348

74-
2. You need to install cert-manager, and setup issuers (https://docs.cert-manager.io/en/latest/index.html). It's easy to install using helm (which you have anyway, right?). Cert-manager is what will request and renew SSL certificates required for docker-mailserver to work. The chart will assume that you've configured and tested certmanager.
49+
2. You need to install cert-manager, and [setup issuers](https://docs.cert-manager.io/en/latest/index.html). It's easy to install using helm (which you have anyway, right?). Cert-manager is what will request and renew SSL certificates required for `docker-mailserver` to work. The chart will assume that you've configured and tested certmanager.
7550

7651
Here are the TL;DR steps for installing cert-manager:
7752

78-
```
53+
``` CONSOLE
7954
# Install the CustomResourceDefinition resources separately
8055
kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.7/deploy/manifests/00-crds.yaml
8156

@@ -99,19 +74,18 @@ helm install \
9974
jetstack/cert-manager
10075
```
10176

102-
103-
## Installation
104-
105-
```bash
77+
``` CONSOLE
10678
$ helm install --name docker-mailserver docker-mailserver
79+
...
10780
```
108-
(Note: An [issues exists](https://github.com/funkypenguin/docker-mailserver/issues/4) for the support of deploying to a custom namespace)
81+
82+
Note: An [issues exists](https://github.com/docker-mailserver/docker-mailserver-helm/issues/4) for the support of deploying to a custom namespace
10983

11084
## Operation
11185

11286
### Download setup.sh
11387

114-
Download the [upstream setup.sh](https://raw.githubusercontent.com/tomav/docker-mailserver/master/setup.sh) to a local folder (*ideally the same location you store your custom values.yaml*)
88+
Download the [upstream setup.sh](https://raw.githubusercontent.com/docker-mailserver/docker-mailserver/master/setup.sh) to a local folder (*ideally the same location you store your custom values.yaml*)
11589

11690
Run `./setup.sh` without arguments for a list of full options
11791

@@ -120,7 +94,8 @@ Run `./setup.sh` without arguments for a list of full options
12094
Run `./setup.sh <email address>` to create the email addresses in `$PWD/config`
12195

12296
Example output:
123-
```
97+
98+
``` CONSOLE
12499
[funkypenguin:~/demo] ./setup.sh email add david@kowalski.elpenguino.net
125100
"docker inspect" requires at least 1 argument.
126101
See 'docker inspect --help'.
@@ -134,9 +109,9 @@ Enter Password:
134109

135110
### Setup OpenDKIM
136111

137-
138112
Example output:
139-
```
113+
114+
``` CONSOLE
140115
[funkypenguin:~/demo] ./setup.sh config dkim
141116
"docker inspect" requires at least 1 argument.
142117
See 'docker inspect --help'.
@@ -163,15 +138,16 @@ If employing HAProxy with RainLoop, use port 10993 for your IMAPS server, as ill
163138
All configuration values are documented in values.yaml. Check that for references, default values etc. To modify a
164139
configuration value for a chart, you can either supply your own values.yaml overriding the default one in the repo:
165140

166-
```bash
141+
``` CONSOLE
167142
$ helm upgrade --install path/to/docker-mailserver docker-mailserver --values path/to/custom/values/file.yaml
168143
```
169144

170145
Or, you can override an individual configuration setting with `helm upgrade --set`, specifying each parameter using the `--set key=value[,key=value]` argument to `helm install`. For example:
171146

172-
```bash
147+
``` CONSOLE
173148
$ helm upgrade --install path/to/docker-mailserver docker-mailserver --set pod.dockermailserver.image="your/image:1.0.0"
174149
```
150+
175151
#### Minimal configuration
176152

177153
Most of the values recorded belowe are set to sensible default, butyou'll definately want to pay attention to at least the following:
@@ -187,9 +163,6 @@ Most of the values recorded belowe are set to sensible default, butyou'll defina
187163
| `ssl.dnsname` | DNS domain used for DNS01 validation | `example.com` |
188164
| `ssl.dns01provider` | The cert-manager DNS01 provider (*more details [coming](https://github.com/funkypenguin/docker-mailserver/issues/6)*) | `cloudflare` |
189165

190-
191-
192-
193166
#### Chart Configuration
194167

195168
The following table lists the configurable parameters of the docker-mailserver chart and their default values.
@@ -236,9 +209,9 @@ The following table lists the configurable parameters of the docker-mailserver c
236209

237210
#### docker-mailserver Configuration
238211

239-
There are **many** environment variables which allow you to customize the behaviour of docker-mailserver. The function of each variable is described at https://github.com/tomav/docker-mailserver#environment-variables
212+
There are **many** environment variables which allow you to customize the behaviour of docker-mailserver. The function of each variable is described at https://github.com/docker-mailserver/docker-mailserver#environment-variables
240213

241-
Every variable can be set using `values.yaml`, but note that docker-mailserver expects any true/false values to be set as binary numbers (1/0), rather than boolean (true/false). BadThings(tm) will happen if you try to pass an environment variable as "true" when [`start-mailserver.sh`](https://github.com/tomav/docker-mailserver/blob/master/target/start-mailserver.sh) is expecting a 1 or a 0!
214+
Every variable can be set using `values.yaml`, but note that docker-mailserver expects any true/false values to be set as binary numbers (1/0), rather than boolean (true/false). BadThings(tm) will happen if you try to pass an environment variable as "true" when [`start-mailserver.sh`](https://github.com/docker-mailserver/docker-mailserver/blob/master/target/start-mailserver.sh) is expecting a 1 or a 0!
242215

243216
#### Rainloop Configuration
244217

@@ -266,16 +239,6 @@ Values you'll definately want to pay attention to:
266239
| `haproxy.tcp.995` | How to forward inbound TCP connections on port 995. Use syntax described above. | `default/docker-mailserver:995::PROXY-V1` |
267240
| `haproxy.service.externalTrafficPolicy` | Used to preserve source IP per [this doc](https://kubernetes.io/docs/tutorials/services/source-ip/#source-ip-for-services-with-type-loadbalancer) | `Local` |
268241

269-
270-
271-
272-
273-
274-
275-
276-
277-
278-
279242
## Development
280243

281244
### Testing
@@ -292,4 +255,3 @@ If you're comfortable with the changes to the saved snapshot, then regenerate th
292255
helm plugin install https://github.com/lrills/helm-unittest
293256
helm unittest helm-chart/docker-mailserver
294257
```
295-

0 commit comments

Comments
 (0)