From f0e281c54e65e06ac871acb3685037ab2dae0036 Mon Sep 17 00:00:00 2001 From: Devin Richards Date: Thu, 16 Jul 2026 13:50:06 -0400 Subject: [PATCH 1/2] Add TLS Secret support for HTTPS Replace incomplete path-based HTTPS configuration with proper Kubernetes TLS Secret mounting. Users now reference an existing TLS Secret via https.secretName, and the chart automatically mounts files to container paths. --- CLAUDE.md | 74 ++++++++++++++++++++++++ charts/maildev/README.md | 26 ++++++++- charts/maildev/templates/deployment.yaml | 30 ++++++++-- charts/maildev/values.yaml | 10 ++-- 4 files changed, 128 insertions(+), 12 deletions(-) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..1ca1462 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,74 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +This is a Helm chart repository for MailDev, an SMTP server and web interface for development and testing. The repository contains a single chart (`charts/maildev/`) that packages the MailDev application for Kubernetes deployment. + +### Key Files and Structure + +- **`charts/maildev/Chart.yaml`** — Chart metadata including version and appVersion +- **`charts/maildev/values.yaml`** — Default configuration values for the chart +- **`charts/maildev/templates/`** — Kubernetes manifests: + - `deployment.yaml` — Main MailDev deployment with extensive configuration + - `service-smtp.yaml`, `service-web.yaml` — Services for SMTP (port 1025) and web UI (port 1080) + - `cm-auto-relay-rules.yaml` — ConfigMap for SMTP auto-relay rules + - `serviceaccount.yaml` — ServiceAccount for the deployment + - `_helpers.tpl` — Shared template definitions +- **`ct.yaml`** — chart-testing configuration (target branch: main, chart directory: charts) +- **`.github/workflows/`** — CI/CD pipelines: + - `lint-test.yaml` — Runs on PRs; lints and tests changed charts + - `release.yaml` — Publishes charts to GitHub Pages on merges to main + +## Development Commands + +### Linting and Testing Charts + +**Lint all charts:** +```bash +ct lint --config ct.yaml +``` + +**List changed charts (since the target branch):** +```bash +ct list-changed --config ct.yaml +``` + +**Install and test charts on a local Kubernetes cluster:** +```bash +# Requires a running Kubernetes cluster (e.g., kind, minikube, Docker Desktop) +ct install --config ct.yaml +``` + +### Prerequisites for Local Testing + +- **Helm** (v3.16.2+ as used in CI) +- **chart-testing** (Python-based tool) +- **Kubernetes cluster** (for `ct install` tests) + +Install chart-testing: https://github.com/helm/chart-testing + +## Chart Configuration Notes + +The MailDev chart models the following major configurations: + +1. **Image** — Repository, tag, and pull policy (defaults to maildev/maildev at Chart.appVersion) +2. **Ports** — SMTP (1025) and web UI (1080) ports are configurable +3. **Outgoing Relay** — Can relay emails to an external SMTP server with auto-relay rules +4. **Web Interface** — Can be disabled; supports basic auth via user/pass +5. **HTTPS** — Can be enabled with custom key and cert +6. **Escape Hatches** — `extraArgs` (for unmapped MailDev CLI flags) and `extraEnv` (for custom environment variables) + +The deployment uses liveness and readiness probes against `/healthz` on the web port. + +## Release Process + +Chart releases are automated: +1. Changes are merged to `main` +2. The release workflow runs chart-releaser-action, which: + - Detects version bumps in Chart.yaml + - Packages and indexes the chart + - Publishes to GitHub Pages + +To release a new version, bump `version:` in `charts/maildev/Chart.yaml`. diff --git a/charts/maildev/README.md b/charts/maildev/README.md index 57e194e..48dc50c 100644 --- a/charts/maildev/README.md +++ b/charts/maildev/README.md @@ -39,12 +39,32 @@ Not listing here the more general paramaters such as tolerations, nodeSelectors, | **web.disable** | Disable Web interface, `--disable-web`. | `false` | | **web.user** | Web interface user, `MAILDEV_WEB_USER`. Only set when defined. | `` | | **web.pass** | Web interface password, `MAILDEV_WEB_PASS`. Only set when defined. | `` | -| **https.enabled** | Switch from http to https protocol, `MAILDEV_HTTPS`. | `false` | -| **https.key** | The file path to the ssl private key, `MAILDEV_HTTPS_KEY`. | | -| **https.cert** | The file path to the ssl cert file, `MAILDEV_HTTPS_CERT`. | | +| **https.enabled** | Enable HTTPS for the web interface, `MAILDEV_HTTPS`. | `false` | +| **https.secretName** | Name of an existing Kubernetes TLS Secret to use for HTTPS (required when enabled: true). | `` | | **incoming.user** | SMTP user for incoming emails, `MAILDEV_INCOMING_USER`. | | | **incoming.pass** | SMTP password for incoming emails, `MAILDEV_INCOMING_PASS`. | | +## Enabling HTTPS + +To enable HTTPS for the web interface, you must first create a Kubernetes TLS Secret: + +```bash +kubectl create secret tls my-maildev-tls \ + --cert=path/to/tls.crt \ + --key=path/to/tls.key \ + -n your-namespace +``` + +Then enable HTTPS in your Helm values: + +```yaml +https: + enabled: true + secretName: my-maildev-tls +``` + +The TLS certificate and private key will be automatically mounted into the MailDev pod at the expected paths. + ## Test it Open a shell into the pod. diff --git a/charts/maildev/templates/deployment.yaml b/charts/maildev/templates/deployment.yaml index 35212de..053bcf5 100644 --- a/charts/maildev/templates/deployment.yaml +++ b/charts/maildev/templates/deployment.yaml @@ -70,9 +70,9 @@ spec: - name: MAILDEV_HTTPS value: "true" - name: MAILDEV_HTTPS_KEY - value: "{{ .Values.https.key }}" + value: "/etc/ssl/private/tls.key" - name: MAILDEV_HTTPS_CERT - value: "{{ .Values.https.cert }}" + value: "/etc/ssl/certs/tls.crt" {{- end }} {{- if .Values.outgoingRelay.host }} - name: MAILDEV_OUTGOING_HOST @@ -117,17 +117,39 @@ spec: port: {{ .Values.ports.web }} resources: {{- toYaml .Values.resources | nindent 12 }} - {{- if .Values.outgoingRelay.autoRelay.enabled }} volumeMounts: + {{- if .Values.outgoingRelay.autoRelay.enabled }} - name: auto-relay-rules mountPath: /etc/maildev {{- end }} - {{- if .Values.outgoingRelay.autoRelay.enabled }} + {{- if .Values.https.enabled }} + - name: tls-certs + mountPath: /etc/ssl/certs + readOnly: true + - name: tls-key + mountPath: /etc/ssl/private + readOnly: true + {{- end }} volumes: + {{- if .Values.outgoingRelay.autoRelay.enabled }} - name: auto-relay-rules configMap: name: {{ include "maildev.fullname" . }}-relay-rules {{- end }} + {{- if .Values.https.enabled }} + - name: tls-certs + secret: + secretName: {{ .Values.https.secretName }} + items: + - key: tls.crt + path: tls.crt + - name: tls-key + secret: + secretName: {{ .Values.https.secretName }} + items: + - key: tls.key + path: tls.key + {{- end }} {{- with .Values.nodeSelector }} nodeSelector: {{- toYaml . | nindent 8 }} diff --git a/charts/maildev/values.yaml b/charts/maildev/values.yaml index 90f115d..185b315 100644 --- a/charts/maildev/values.yaml +++ b/charts/maildev/values.yaml @@ -58,13 +58,13 @@ ports: # MAILDEV_WEB_PORT web: 1080 -# MAILDEV_HTTPS +# MAILDEV_HTTPS - Enable TLS for the web interface https: enabled: false - # MAILDEV_HTTPS_KEY - # key: - # MAILDEV_HTTPS_KEY - # cert: + # Name of an existing Kubernetes TLS Secret to use for HTTPS. + # The secret must be of type kubernetes.io/tls and contain tls.crt and tls.key keys. + # Required when enabled: true + # secretName: my-tls-secret # Web interface web: From 3c21b1618c50709cb12f78d13ba97cf478050d7a Mon Sep 17 00:00:00 2001 From: Devin Richards Date: Thu, 16 Jul 2026 14:02:21 -0400 Subject: [PATCH 2/2] Updated healthz endpoint to match new /api/healthz --- charts/maildev/templates/NOTES.txt | 2 +- charts/maildev/templates/deployment.yaml | 6 ++++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/charts/maildev/templates/NOTES.txt b/charts/maildev/templates/NOTES.txt index 34a2b1e..8857469 100644 --- a/charts/maildev/templates/NOTES.txt +++ b/charts/maildev/templates/NOTES.txt @@ -1,6 +1,6 @@ {{- if contains "ClusterIP" .Values.service.type }} - echo http://127.0.0.1:1080/ + echo {{ if .Values.https.enabled }}https{{ else }}http{{ end }}://127.0.0.1:1080/ kubectl port-forward $(kubectl get pod -l "app.kubernetes.io/instance=maildev" -o name) 1080:1080 {{- else }} diff --git a/charts/maildev/templates/deployment.yaml b/charts/maildev/templates/deployment.yaml index 053bcf5..3233a1d 100644 --- a/charts/maildev/templates/deployment.yaml +++ b/charts/maildev/templates/deployment.yaml @@ -109,11 +109,13 @@ spec: {{- end }} livenessProbe: httpGet: - path: /healthz + scheme: {{ if .Values.https.enabled }}HTTPS{{ else }}HTTP{{ end }} + path: /api/healthz port: {{ .Values.ports.web }} readinessProbe: httpGet: - path: /healthz + scheme: {{ if .Values.https.enabled }}HTTPS{{ else }}HTTP{{ end }} + path: /api/healthz port: {{ .Values.ports.web }} resources: {{- toYaml .Values.resources | nindent 12 }}