From a88778f08b54649572ac1ca3a7e46acce1a36464 Mon Sep 17 00:00:00 2001 From: Georg Lauterbach <44545919+georglauterbach@users.noreply.github.com> Date: Wed, 29 Dec 2021 14:46:32 +0100 Subject: [PATCH] update `README.md`, looking for maintainers --- README.md | 104 +++++++++++++++++------------------------------------- 1 file changed, 33 insertions(+), 71 deletions(-) diff --git a/README.md b/README.md index d74d0dc1..0235627c 100644 --- a/README.md +++ b/README.md @@ -1,51 +1,26 @@ -# Docker-mailserver +# K8s Helm Chart for Docker Mailserver -[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/). +[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. -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). +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). + +**_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. ## Introduction -This helm chart deploys docker-mailserver into a Kubernetes cluster, in a manner which retains compatibility with the upstream, docker-specific version. - -## Contents - -- [Docker-mailserver](#docker-mailserver) - - [Introduction](#introduction) - - [Contents](#contents) - - [Features](#features) - - [Prerequisites](#prerequisites) - - [Architecture](#architecture) - - [Installation](#installation) - - [Install helm and cert-manager](#install-helm-and-cert-manager) - - [Installation](#installation-1) - - [Operation](#operation) - - [Download setup.sh](#download-setupsh) - - [Create / Update / Delete users](#create--update--delete-users) - - [Setup OpenDKIM](#setup-opendkim) - - [Setup RainLoop](#setup-rainloop) - - [Configuration](#configuration) - - [Minimal configuration](#minimal-configuration) - - [Chart Configuration](#chart-configuration) - - [docker-mailserver Configuration](#docker-mailserver-configuration) - - [Rainloop Configuration](#rainloop-configuration) - - [HA Proxy-Ingress Configuration](#ha-proxy-ingress-configuration) - - [Development](#development) - - [Testing](#testing) - -(Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc.go)) - -## Features +This helm chart deploys docker-mailserver into a Kubernetes cluster, in a manner which retains compatibility with the upstream, docker-specific version. + +## Features The chart includes the following features: -* All configuration is done in values.yaml, or using the native "setup.sh" script (to create mailboxes or DKIM keys) -* 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) -* Employs [cert-manager](https://github.com/jetstack/cert-manager) to automatically provide/renew SSL certificates -* Bundles in [RainLoop](https://www.rainloop.net) for webmail access (disabled by default) -* Starts in "demo" mode, allowing the user to test core functionality before configuring for specific domains -* 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) -* +- All configuration is done in values.yaml, or using the native "setup.sh" script (to create mailboxes or DKIM keys) +- 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) +- Employs [cert-manager](https://github.com/jetstack/cert-manager) to automatically provide/renew SSL certificates +- Bundles in [RainLoop](https://www.rainloop.net) for webmail access (disabled by default) +- Starts in "demo" mode, allowing the user to test core functionality before configuring for specific domains +- 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) + ## Prerequisites - 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 - __Suggested:__ PV provisioner support in the underlying infrastructure - [Cert-manager](https://github.com/jetstack/cert-manager/tree/master/deploy/charts/cert-manager) requires manual deployment into your cluster (details below) - [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*) -- 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 +- 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 ## Architecture -There are several ways you might deploy docker-mailserver. The most common would be: +There are several ways you might deploy `docker-mailserver`. The most common would be: 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 @@ -71,11 +46,11 @@ There are several ways you might deploy docker-mailserver. The most common would 1. You need helm, obviously. -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. +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. Here are the TL;DR steps for installing cert-manager: -``` +``` CONSOLE # Install the CustomResourceDefinition resources separately kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.7/deploy/manifests/00-crds.yaml @@ -99,19 +74,18 @@ helm install \ jetstack/cert-manager ``` - -## Installation - -```bash +``` CONSOLE $ helm install --name docker-mailserver docker-mailserver +... ``` -(Note: An [issues exists](https://github.com/funkypenguin/docker-mailserver/issues/4) for the support of deploying to a custom namespace) + +Note: An [issues exists](https://github.com/docker-mailserver/docker-mailserver-helm/issues/4) for the support of deploying to a custom namespace ## Operation ### Download setup.sh -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*) +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*) Run `./setup.sh` without arguments for a list of full options @@ -120,7 +94,8 @@ Run `./setup.sh` without arguments for a list of full options Run `./setup.sh ` to create the email addresses in `$PWD/config` Example output: -``` + +``` CONSOLE [funkypenguin:~/demo] ./setup.sh email add david@kowalski.elpenguino.net "docker inspect" requires at least 1 argument. See 'docker inspect --help'. @@ -134,9 +109,9 @@ Enter Password: ### Setup OpenDKIM - Example output: -``` + +``` CONSOLE [funkypenguin:~/demo] ./setup.sh config dkim "docker inspect" requires at least 1 argument. See 'docker inspect --help'. @@ -163,15 +138,16 @@ If employing HAProxy with RainLoop, use port 10993 for your IMAPS server, as ill All configuration values are documented in values.yaml. Check that for references, default values etc. To modify a configuration value for a chart, you can either supply your own values.yaml overriding the default one in the repo: -```bash +``` CONSOLE $ helm upgrade --install path/to/docker-mailserver docker-mailserver --values path/to/custom/values/file.yaml ``` 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: -```bash +``` CONSOLE $ helm upgrade --install path/to/docker-mailserver docker-mailserver --set pod.dockermailserver.image="your/image:1.0.0" ``` + #### Minimal configuration 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 | `ssl.dnsname` | DNS domain used for DNS01 validation | `example.com` | | `ssl.dns01provider` | The cert-manager DNS01 provider (*more details [coming](https://github.com/funkypenguin/docker-mailserver/issues/6)*) | `cloudflare` | - - - #### Chart Configuration 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 #### docker-mailserver Configuration -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 +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 -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! +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! #### Rainloop Configuration @@ -266,16 +239,6 @@ Values you'll definately want to pay attention to: | `haproxy.tcp.995` | How to forward inbound TCP connections on port 995. Use syntax described above. | `default/docker-mailserver:995::PROXY-V1` | | `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` | - - - - - - - - - - ## Development ### Testing @@ -292,4 +255,3 @@ If you're comfortable with the changes to the saved snapshot, then regenerate th helm plugin install https://github.com/lrills/helm-unittest helm unittest helm-chart/docker-mailserver ``` -