feat: add Helm chart for Kubernetes deployment

.github/workflows/helm.yml

@@ -0,0 +1,110 @@
+name: Helm
+
+on:
+  push:
+    branches: [main]
+    tags: ["*"]
+    paths:
+      - "charts/**"
+      - ".github/workflows/helm.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "charts/**"
+      - ".github/workflows/helm.yml"
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Helm Setup
+        uses: azure/setup-helm@v5.0.0
+
+      - name: Python Setup
+        uses: actions/setup-python@v5
+        with:
+          python-version: ">=3.13"
+
+      - name: Install chart-testing
+        env:
+          CT_VERSION: "3.11.0"
+        run: |
+          pip install yamllint yamale --quiet
+          curl -sSLo ct.tar.gz "https://github.com/helm/chart-testing/releases/download/v${CT_VERSION}/chart-testing_${CT_VERSION}_linux_amd64.tar.gz"
+          tar -xzf ct.tar.gz ct
+          sudo mv ct /usr/local/bin/ct
+          rm ct.tar.gz
+
+      - name: List changed charts
+        id: list-changed
+        run: |
+          changed=$(ct list-changed \
+            --chart-dirs charts \
+            --target-branch "${{ github.event.repository.default_branch }}")
+          if [ -n "$changed" ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Lint changed charts
+        if: steps.list-changed.outputs.changed == 'true'
+        run: |
+          ct lint \
+            --chart-dirs charts \
+            --target-branch "${{ github.event.repository.default_branch }}"
+
+      - name: Render templates
+        run: |
+          helm template terminus charts/terminus \
+            --set secrets.databaseUrl="postgres://user:pass@db:5432/terminus" \
+            --set secrets.keyvalueUrl="redis://:pass@redis:6379/0" \
+            --set secrets.appSecret="ci0000000000000000000000000000000000000000000000000000000000000000" \
+            --set config.apiUri="https://terminus.example.com"
+
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    needs: lint
+    if: startsWith(github.ref, 'refs/tags/')
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Helm Setup
+        uses: azure/setup-helm@v5.0.0
+
+      - name: Extract Version
+        id: version
+        run: |
+          VERSION="${GITHUB_REF#refs/tags/v}"
+          echo "version=${VERSION}" >> "${GITHUB_OUTPUT}"
+
+      - name: Registry Login
+        run: |
+          echo "${{ github.token }}" | helm registry login ghcr.io \
+            --username "${{ github.actor }}" \
+            --password-stdin
+
+      - name: Update Dependencies
+        run: helm dependency update charts/terminus
+
+      - name: Package Chart
+        run: |
+          helm package charts/terminus \
+            --version "${{ steps.version.outputs.version }}" \
+            --app-version "${{ steps.version.outputs.version }}"
+
+      - name: Push Chart
+        run: |
+          helm push "terminus-${{ steps.version.outputs.version }}.tgz" \
+            oci://ghcr.io/${{ github.repository_owner }}/charts

README.adoc

@@ -10,6 +10,7 @@
 :doc_development_link: link:https://github.com/usetrmnl/terminus/blob/main/doc/development.adoc[Development]
 :doc_docker_link: link:https://github.com/usetrmnl/terminus/blob/main/doc/docker.adoc[Docker]
 :doc_extensions_link: link:https://github.com/usetrmnl/terminus/blob/main/doc/extensions.adoc[Extensions]
+:doc_helm_link: link:https://github.com/usetrmnl/terminus/blob/main/doc/helm.adoc[Helm Chart]
 :doc_jobs_link: link:https://github.com/usetrmnl/terminus/blob/main/doc/jobs.adoc[Jobs]
 :doc_kubernetes_link: link:https://github.com/usetrmnl/terminus/blob/main/doc/kubernetes.adoc[Kubernetes]
 :doc_raspberry_pi_link: link:https://github.com/usetrmnl/terminus/blob/main/doc/raspberry_pi.adoc[Raspberry PI]
@@ -223,6 +224,10 @@ See {doc_raspberry_pi_link} documentation for details.
 
 See {doc_kubernetes_link} documentation for details.
 
+=== Helm Chart
+
+See {doc_helm_link} documentation for details.
+
 === Render
 
 See {doc_render_link} documentation for details.

charts/terminus/Chart.yaml

@@ -0,0 +1,6 @@
+apiVersion: v2
+name: terminus
+description: A Helm chart for Terminus - a self-hosted TRMNL server
+type: application
+version: 0.1.0
+appVersion: "latest"

charts/terminus/ci/default-values.yaml

@@ -0,0 +1,11 @@
+# Values used by chart-testing (ct lint) only.
+# The chart requires non-empty connection settings and an app secret, so
+# linting against bare defaults would fail the validation guards in
+# _helpers.tpl. These are throwaway values and are never deployed.
+config:
+  apiUri: "https://terminus.example.com"
+
+secrets:
+  databaseUrl: "postgres://user:pass@postgres:5432/terminus"
+  keyvalueUrl: "redis://redis:6379/0"
+  appSecret: "ci0000000000000000000000000000000000000000000000000000000000000000"

charts/terminus/templates/NOTES.txt

@@ -0,0 +1,51 @@
+Terminus has been deployed successfully.
+
+Web URL:
+{{- if .Values.route.enabled }}
+  http{{ if .Values.route.host }}s{{ end }}://{{ .Values.route.host }}
+{{- else if .Values.ingress.enabled }}
+  http{{ if .Values.ingress.tls }}s{{ end }}://{{ .Values.ingress.host }}
+{{- else }}
+  export POD=$(kubectl get pods --namespace {{ .Release.Namespace }} -l "app.kubernetes.io/name={{ include "terminus.name" . }},app.kubernetes.io/component=web" -o jsonpath="{.items[0].metadata.name}")
+  kubectl --namespace {{ .Release.Namespace }} port-forward $POD 2345:{{ .Values.config.hanamiPort }}
+  Visit http://127.0.0.1:2345
+{{- end }}
+
+Components deployed:
+  - Deployment {{ include "terminus.fullname" . }}-web
+      - web    (Puma)
+      - worker (Sidekiq sidecar)
+{{- if .Values.migrate.enabled }}
+  - Job {{ include "terminus.fullname" . }}-migrate (pre-install/pre-upgrade hook)
+{{- end }}
+{{- if .Values.database.enabled }}
+  - Deployment {{ include "terminus.fullname" . }}-database (bundled PostgreSQL, single instance)
+{{- end }}
+{{- if .Values.keyvalue.enabled }}
+  - Deployment {{ include "terminus.fullname" . }}-keyvalue (bundled Valkey, single instance)
+{{- end }}
+{{- if or .Values.database.enabled .Values.keyvalue.enabled }}
+
+Bundled datastores have no replication, backups or failover. Take your own
+backups, and prefer managed services for production.
+{{- end }}
+
+{{- if .Values.vault.enabled }}
+
+Secrets: managed by Vault Agent Injector
+  Path: {{ .Values.vault.secretPath }}
+  Role: {{ .Values.vault.role }}
+{{- else }}
+Secrets: stored in Kubernetes Secret
+  Name: {{ include "terminus.fullname" . }}
+{{- end }}
+
+{{- if .Values.autoscaling.enabled }}
+
+Autoscaling: enabled (scales the pod — web + worker sidecar scale together)
+  Min: {{ .Values.autoscaling.minReplicas }} / Max: {{ .Values.autoscaling.maxReplicas }}
+{{- end }}
+
+Troubleshooting:
+  kubectl logs -n {{ .Release.Namespace }} deployment/{{ include "terminus.fullname" . }}-web -c web
+  kubectl logs -n {{ .Release.Namespace }} deployment/{{ include "terminus.fullname" . }}-web -c worker

charts/terminus/templates/_helpers.tpl

@@ -0,0 +1,134 @@
+{{/*
+Expand the name of the chart.
+*/}}
+{{- define "terminus.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Create a default fully qualified app name.
+*/}}
+{{- define "terminus.fullname" -}}
+{{- if .Values.fullnameOverride }}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- $name := default .Chart.Name .Values.nameOverride }}
+{{- if contains $name .Release.Name }}
+{{- .Release.Name | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
+{{- end }}
+{{- end }}
+{{- end }}
+
+{{/*
+Chart label
+*/}}
+{{- define "terminus.chart" -}}
+{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Common labels
+*/}}
+{{- define "terminus.labels" -}}
+helm.sh/chart: {{ include "terminus.chart" . }}
+{{ include "terminus.selectorLabels" . }}
+{{- if .Chart.AppVersion }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end }}
+
+{{/*
+Selector labels
+*/}}
+{{- define "terminus.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "terminus.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end }}
+
+{{/*
+ServiceAccount name
+*/}}
+{{- define "terminus.serviceAccountName" -}}
+{{- if .Values.serviceAccount.create }}
+{{- default (include "terminus.fullname" .) .Values.serviceAccount.name }}
+{{- else }}
+{{- default "default" .Values.serviceAccount.name }}
+{{- end }}
+{{- end }}
+
+{{/*
+Connection URLs. A bundled service wins over the corresponding secrets.* value,
+which is documented as ignored in that case.
+*/}}
+{{- define "terminus.databaseUrl" -}}
+{{- if .Values.database.enabled -}}
+{{- $a := .Values.database.auth -}}
+{{- printf "postgres://%s:%s@%s-database:%v/%s" $a.username $a.password (include "terminus.fullname" .) .Values.database.port $a.database -}}
+{{- else -}}
+{{- .Values.secrets.databaseUrl -}}
+{{- end -}}
+{{- end }}
+
+{{- define "terminus.keyvalueUrl" -}}
+{{- if .Values.keyvalue.enabled -}}
+{{- $pass := .Values.keyvalue.auth.password -}}
+{{- printf "redis://%s%s-keyvalue:%v/%s" (ternary (printf ":%s@" $pass) "" (ne $pass "")) (include "terminus.fullname" .) .Values.keyvalue.port .Values.keyvalue.database -}}
+{{- else -}}
+{{- .Values.secrets.keyvalueUrl -}}
+{{- end -}}
+{{- end }}
+
+{{/*
+Render a map as annotations or labels.
+
+Values are quoted rather than passed through toYaml: the API server requires
+string values, and toYaml would emit an unquoted true/false or a bare number
+for anything the values file did not already quote.
+*/}}
+{{- define "terminus.stringMap" -}}
+{{- range $key, $value := . }}
+{{ $key }}: {{ $value | quote }}
+{{- end }}
+{{- end }}
+
+{{/*
+Validate mutually exclusive values
+*/}}
+{{- define "terminus.validateValues" -}}
+{{- if and .Values.ingress.enabled .Values.route.enabled }}
+{{- fail "ingress.enabled and route.enabled are mutually exclusive; enable only one." }}
+{{- end }}
+{{- if and .Values.migrate.enabled .Values.vault.enabled (not .Values.vault.migrateInject) (not .Values.migrate.databaseUrl) }}
+{{- fail "migrate.databaseUrl is required when vault.enabled and migrate.enabled; the migration job runs without the Vault Agent. Set vault.migrateInject to read it from Vault instead." }}
+{{- end }}
+{{- if not .Values.config.apiUri }}
+{{- fail "config.apiUri is required; Hanami constrains api_uri to be non-empty and it has no default." }}
+{{- end }}
+{{/*
+Empty env vars override the application defaults rather than falling back to
+them, so an unset secret surfaces as a settings validation crash at boot.
+*/}}
+{{- if and .Values.vault.enabled (or .Values.database.enabled .Values.keyvalue.enabled) }}
+{{- fail "database.enabled and keyvalue.enabled cannot be combined with vault.enabled; Vault supplies the connection URLs, so a bundled service has nothing to provide them to." }}
+{{- end }}
+{{- if and .Values.database.enabled .Values.migrate.enabled }}
+{{- fail "database.enabled requires migrate.enabled=false; the migration job is a pre-install hook and runs before the bundled database exists. Migrations run at pod startup instead via config.appSetup." }}
+{{- end }}
+{{- if and .Values.database.enabled (not .Values.database.auth.password) }}
+{{- fail "database.auth.password is required when database.enabled." }}
+{{- end }}
+{{- if not .Values.vault.enabled }}
+{{- if not (include "terminus.databaseUrl" .) }}
+{{- fail "secrets.databaseUrl is required when vault.enabled is false and database.enabled is false." }}
+{{- end }}
+{{- if not (include "terminus.keyvalueUrl" .) }}
+{{- fail "secrets.keyvalueUrl is required when vault.enabled is false and keyvalue.enabled is false." }}
+{{- end }}
+{{- if lt (len .Values.secrets.appSecret) 64 }}
+{{- fail "secrets.appSecret is required when vault.enabled is false and must be at least 64 characters (try: openssl rand -hex 64)." }}
+{{- end }}
+{{- end }}
+{{- end }}

charts/terminus/templates/configmap-migrate.yaml

@@ -0,0 +1,24 @@
+{{- if .Values.migrate.enabled -}}
+{{/*
+Hook-scoped copy of the main ConfigMap. The migrate Job runs as a pre-install
+hook, which executes before ordinary release resources exist, so it cannot
+reference the release-managed ConfigMap.
+*/}}
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {{ include "terminus.fullname" . }}-migrate
+  labels:
+    {{- include "terminus.labels" . | nindent 4 }}
+    app.kubernetes.io/component: migrate
+  annotations:
+    helm.sh/hook: pre-install,pre-upgrade
+    helm.sh/hook-weight: "-5"
+    helm.sh/hook-delete-policy: before-hook-creation
+data:
+  API_URI: {{ .Values.config.apiUri | quote }}
+  TZ: {{ .Values.config.tz | quote }}
+  # The Job invokes `hanami db migrate` directly rather than going through the
+  # entrypoint, so the startup setup routine must not run here as well.
+  APP_SETUP: "false"
+{{- end }}

charts/terminus/templates/configmap.yaml

@@ -0,0 +1,13 @@
+{{- include "terminus.validateValues" . }}
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {{ include "terminus.fullname" . }}
+  labels:
+    {{- include "terminus.labels" . | nindent 4 }}
+data:
+  HANAMI_PORT: {{ .Values.config.hanamiPort | quote }}
+  API_URI: {{ .Values.config.apiUri | quote }}
+  APP_SETUP: {{ .Values.config.appSetup | quote }}
+  TZ: {{ .Values.config.tz | quote }}
+  RACK_ATTACK_ALLOWED_SUBNETS: {{ .Values.config.rackAttackAllowedSubnets | quote }}