📝 start documenting setups with the Helm Chart

mailu/README.md

@@ -325,14 +325,15 @@ Check that the deployed pods are all running.
 | `front.externalService.ports.smtps`           | Expose SMTP port (TLS) - 465/tcp                                                      | `true`          |
 | `front.externalService.ports.submission`      | Expose Submission port - 587/tcp                                                      | `false`         |
 | `front.externalService.ports.manageSieve`     | Expose ManageSieve port - 4190/tcp                                                    | `true`          |
-| `front.externalService.nodePorts.pop3`        | NodePort to use for POP3 (defaults to 110/tcp)                                        | `110`           |
-| `front.externalService.nodePorts.pop3s`       | NodePort to use for POP3 (TLS) (defaults to 995/tcp)                                  | `995`           |
-| `front.externalService.nodePorts.imap`        | NodePort to use for IMAP (defaults to 143/tcp)                                        | `143`           |
-| `front.externalService.nodePorts.imaps`       | NodePort to use for IMAP (TLS) (defaults to 993/tcp)                                  | `993`           |
-| `front.externalService.nodePorts.smtp`        | NodePort to use for SMTP (defaults to 25/tcp)                                         | `25`            |
-| `front.externalService.nodePorts.smtps`       | NodePort to use for SMTP (TLS) (defaults to 465/tcp)                                  | `465`           |
-| `front.externalService.nodePorts.submission`  | NodePort to use for Submission (defaults to 587/tcp)                                  | `587`           |
-| `front.externalService.nodePorts.manageSieve` | NodePort to use for ManageSieve (defaults to 4190/tcp)                                | `4190`          |
+| `front.externalService.nodePorts`             | Optionally define NodePorts.                                                          | `{}`            |
+| `front.externalService.nodePorts.pop3`        | NodePort to use for POP3                                                              | `undefined`     |
+| `front.externalService.nodePorts.pop3s`       | NodePort to use for POP3 (TLS)                                                        | `undefined`     |
+| `front.externalService.nodePorts.imap`        | NodePort to use for IMAP                                                              | `undefined`     |
+| `front.externalService.nodePorts.imaps`       | NodePort to use for IMAP (TLS)                                                        | `undefined`     |
+| `front.externalService.nodePorts.smtp`        | NodePort to use for SMTP                                                              | `undefined`     |
+| `front.externalService.nodePorts.smtps`       | NodePort to use for SMTP (TLS)                                                        | `undefined`     |
+| `front.externalService.nodePorts.submission`  | NodePort to use for Submission                                                        | `undefined`     |
+| `front.externalService.nodePorts.manageSieve` | NodePort to use for ManageSieve                                                       | `undefined`     |
 | `front.kind`                                  | Kind of resource to create for the front (`Deployment` or `DaemonSet`)                | `Deployment`    |
 | `front.replicaCount`                          | Number of front replicas to deploy (only for `Deployment` kind)                       | `1`             |
 | `front.resources.limits`                      | The resources limits for the container                                                | `{}`            |

mailu/SETUPS.md

@@ -0,0 +1,100 @@
+# Mailu setups with the Helm Chart
+
+WIP: This document shall describe and show how Mailu can be setup with the Helm Chart.
+
+> [!IMPORTANT]
+> Routing all traffic, including Web traffic through the Mailu `front` service is done **on purpose** to deliver
+> an integrated service to the users of Mailu. You are free to run components separately, but such setups are not in scope
+> of the Mailu project or the Mailu Helm Chart and are not supported. Using `HTTPS` as backend for the ingress is also a
+> conscious decision and allows for an integrated experience while keeping the scope small for the volunteer dev team.
+
+## Simple setup
+
+This is a simple setup to make Mailu services available from the internet.
+Cert-manager is used to get a certificate for the Ingress. The same certificate is used by the `front` deployment for
+mail services.
+
+How traffic is routed from a public IP address to individual K8s nodes is out of scope and must be taken care of individually.
+Typically K8s nodes have private IP addresses and a Service of type LoadBalancer is used to make services available on public IPs.
+
+This setup is using a single instance where Mail services will be reachable either through HostPort or
+a Service of type NodePort or LoadBalancer.
+
+```mermaid
+flowchart TD
+    %% entities
+    Internet(Internet)
+    Ingress("`**Ingress**
+    service`")
+    FrontService("`**NodePort/LoadBalancer**
+    service`")
+    Front("`**Mailu front**
+    single pod`")
+    Webmail("`**Mailu webmail**
+    single pod`")
+    MailServices("`**Mailu smtp/imap...**
+    pods`")
+
+
+    Internet --> Node1
+    Internet --> Node2
+
+    subgraph Node1[k8s node 1]
+        IngressController1 -- 80/443 --> Ingress
+    end
+
+    subgraph Node2[k8s node 2]
+        IngressController2 -- 80/443 --> Ingress
+
+        FrontService -- 25/.../995 --> Front
+        HostPort["`**HostPort**`"] -- 25/.../995 --> Front
+        Ingress -- HTTPS --> Front
+
+        Front --> MailServices
+        Front --> Webmail
+    end
+```
+
+### Using HostPort (default)
+
+- Ingress for Webmail (80, 443)
+- Host port for Mail ports (25, 110, 143, 465, 587, 993, 995)
+
+### Using NodePort
+
+Same as the above, but using a Service of type `NodePort` to bind K8s node ports to the mail services.
+
+```yaml
+# values.yaml
+front:
+  hostPort:
+    enabled: false
+  externalService:
+    enabled: true
+    type: NodePort
+    nodePort:
+      # optionally define specific ports
+      imaps: 30995
+```
+
+### Using LoadBalancer
+
+Again the same as above, but using a Service of type `LoadBalancer` to assign a public IP on which to reach the mail services:
+
+```yaml
+# values.yaml
+front:
+  hostPort:
+    enabled: false
+  externalService:
+    enabled: true
+    type: LoadBalancer
+```
+
+## K8s nodes with public IPs
+
+> [!WARNING]
+> Traffic between pods is unencrypted, use [istio](https://istio.io/) or similar to ensure traffic between pods of the k8s nodes is encrypted.
+
+If your cluster nodes use public IPs, you can directly access the mail ports from the internet, for example using the
+default HostPort or a NodePort Service described above.

mailu/ci/helm-lint-values.yaml

@@ -1,12 +1,12 @@
 hostnames:
-  - example.com
+  - mailu.cluster.local
 
-domain: example.com
+domain: mailu.cluster.local
 
 initialAccount:
   enabled: true
   username: mailadmin
-  domain: example.com
+  domain: mailu.cluster.local
   password: chang3m3!
 
 secretKey: chang3m3!

mailu/templates/front/service-external.yaml

@@ -27,63 +27,63 @@ spec:
     - name: pop3
       port: 110
       protocol: TCP
-      {{ if eq $.Values.front.externalService.type "NodePort" -}}
+      {{- if and (eq $.Values.front.externalService.type "NodePort") .nodePorts.pop3 }}
       nodePort: {{ .nodePorts.pop3 }}
       {{- end }}
     {{- end }}
     {{- if .ports.pop3s }}
     - name: pop3s
       port: 995
       protocol: TCP
-      {{ if eq $.Values.front.externalService.type "NodePort" -}}
+      {{- if and (eq $.Values.front.externalService.type "NodePort") .nodePorts.pop3s }}
       nodePort: {{ .nodePorts.pop3s }}
       {{- end }}
     {{- end }}
     {{- if .ports.imap }}
     - name: imap
       port: 143
       protocol: TCP
-      {{ if eq $.Values.front.externalService.type "NodePort" -}}
+      {{- if and (eq $.Values.front.externalService.type "NodePort") .nodePorts.imap }}
       nodePort: {{ .nodePorts.imap }}
       {{- end }}
     {{- end }}
     {{- if .ports.imaps }}
     - name: imaps
       port: 993
       protocol: TCP
-      {{ if eq $.Values.front.externalService.type "NodePort" -}}
+      {{- if and (eq $.Values.front.externalService.type "NodePort") .nodePorts.imaps }}
       nodePort: {{ .nodePorts.imaps }}
       {{- end }}
     {{- end }}
     {{- if .ports.smtp }}
     - name: smtp
       port: 25
       protocol: TCP
-      {{ if eq $.Values.front.externalService.type "NodePort" -}}
+      {{- if and (eq $.Values.front.externalService.type "NodePort") .nodePorts.smtp }}
       nodePort: {{ .nodePorts.smtp }}
       {{- end }}
     {{- end }}
     {{- if .ports.smtps }}
     - name: smtps
       port: 465
       protocol: TCP
-      {{ if eq $.Values.front.externalService.type "NodePort" -}}
+      {{- if and (eq $.Values.front.externalService.type "NodePort") .nodePorts.smtps }}
       nodePort: {{ .nodePorts.smtps }}
       {{- end }}
     {{- end }}
     {{- if .ports.submission }}
     - name: smtpd
       port: 587
       protocol: TCP
-      {{ if eq $.Values.front.externalService.type "NodePort" -}}
+      {{- if and (eq $.Values.front.externalService.type "NodePort") .nodePorts.submission }}
       nodePort: {{ .nodePorts.submission }}
       {{- end }}
     {{- end }}
     {{- if .ports.manageSieve }}
     - name: sieve
       port: 4190
       protocol: TCP
-      {{ if eq $.Values.front.externalService.type "NodePort" -}}
+      {{- if and (eq $.Values.front.externalService.type "NodePort") .nodePorts.manageSieve }}
       nodePort: {{ .nodePorts.manageSieve }}
       {{- end }}
     {{- end }}

mailu/templates/tests/test-connection.yaml

@@ -0,0 +1,22 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: "{{ include "mailu.fullname" . }}-test-connection"
+  labels: {{- include "common.labels.standard" . | nindent 4 }}
+  annotations:
+    "helm.sh/hook": test
+spec:
+  containers:
+    - name: wget
+      image: busybox
+      command: ['/bin/sh']
+      args:
+        - '-c'
+        - |
+          {{- range .Values.hostnames }}
+          # HTTP redirects to HTTPS
+          wget -S --header "Host: {{ . }}" 'http://{{ printf "%s-front" (include "mailu.fullname" $) }}.{{ include "common.names.namespace" $ }}.svc.cluster.local'
+          # HTTPS redirects to SSO page
+          wget -S --header "Host: {{ . }}" 'https://{{ printf "%s-front" (include "mailu.fullname" $) }}.{{ include "common.names.namespace" $ }}.svc.cluster.local'
+          {{- end }}
+  restartPolicy: Never

mailu/values.yaml

@@ -687,14 +687,15 @@ front:
   ## @param front.externalService.ports.smtps Expose SMTP port (TLS) - 465/tcp
   ## @param front.externalService.ports.submission Expose Submission port - 587/tcp
   ## @param front.externalService.ports.manageSieve Expose ManageSieve port - 4190/tcp
-  ## @param front.externalService.nodePorts.pop3 NodePort to use for POP3 (defaults to 110/tcp)
-  ## @param front.externalService.nodePorts.pop3s NodePort to use for POP3 (TLS) (defaults to 995/tcp)
-  ## @param front.externalService.nodePorts.imap NodePort to use for IMAP (defaults to 143/tcp)
-  ## @param front.externalService.nodePorts.imaps NodePort to use for IMAP (TLS) (defaults to 993/tcp)
-  ## @param front.externalService.nodePorts.smtp NodePort to use for SMTP (defaults to 25/tcp)
-  ## @param front.externalService.nodePorts.smtps NodePort to use for SMTP (TLS) (defaults to 465/tcp)
-  ## @param front.externalService.nodePorts.submission NodePort to use for Submission (defaults to 587/tcp)
-  ## @param front.externalService.nodePorts.manageSieve NodePort to use for ManageSieve (defaults to 4190/tcp)
+  ## @param front.externalService.nodePorts [nullable] Optionally define NodePorts.
+  ## @param front.externalService.nodePorts.pop3 [nullable] NodePort to use for POP3
+  ## @param front.externalService.nodePorts.pop3s [nullable] NodePort to use for POP3 (TLS)
+  ## @param front.externalService.nodePorts.imap [nullable] NodePort to use for IMAP
+  ## @param front.externalService.nodePorts.imaps [nullable] NodePort to use for IMAP (TLS)
+  ## @param front.externalService.nodePorts.smtp [nullable] NodePort to use for SMTP
+  ## @param front.externalService.nodePorts.smtps [nullable] NodePort to use for SMTP (TLS)
+  ## @param front.externalService.nodePorts.submission [nullable] NodePort to use for Submission
+  ## @param front.externalService.nodePorts.manageSieve [nullable] NodePort to use for ManageSieve
   externalService:
     enabled: false
     type: ClusterIP
@@ -712,15 +713,15 @@ front:
       smtps: true
       submission: false
       manageSieve: true
-    nodePorts:
-      pop3: 110
-      pop3s: 995
-      imap: 143
-      imaps: 993
-      smtp: 25
-      smtps: 465
-      submission: 587
-      manageSieve: 4190
+    nodePorts: {}
+      # pop3: 110
+      # pop3s: 995
+      # imap: 143
+      # imaps: 993
+      # smtp: 25
+      # smtps: 465
+      # submission: 587
+      # manageSieve: 4190
 
   ## @param front.kind Kind of resource to create for the front (`Deployment` or `DaemonSet`)
   kind: Deployment