docs(examples): Helm Chart Deployment

# Helm Chart Deployment

Deploy mdbook-htmx using a Helm chart for easier configuration and upgrades.

## Implementation

The Helm chart lives in the aRustyDev/helm-charts repository:

**Repository:** `https://github.com/aRustyDev/helm-charts`
**Chart Path:** `charts/mdbook-htmx`

Features grow with each mdbook-htmx phase:

| Phase | Features |
|-------|----------|
| v0.1.0 | Static serving, health checks |
| v0.2.0 | HTMX fragment routing via Ingress |
| v0.3.0 | OAuth2 proxy sidecar |
| v0.4.0 | Meilisearch StatefulSet |
| v1.0.0 | HPA, PDB, ServiceMonitor |

See [ADR-0016](../adr/0016-implementation-phasing-strategy.md) for details.

## Chart Structure

```
charts/mdbook-htmx/
├── Chart.yaml
├── values.yaml
├── README.md
├── templates/
│ ├── _helpers.tpl
│ ├── deployment.yaml
│ ├── service.yaml
│ ├── ingress.yaml
│ ├── configmap.yaml
│ ├── serviceaccount.yaml
│ ├── hpa.yaml # Phase 5
│ ├── pdb.yaml # Phase 5
│ ├── servicemonitor.yaml # Phase 5
│ ├── oauth2-proxy-*.yaml # Phase 3
│ └── meilisearch-*.yaml # Phase 4
└── NOTES.txt
```

## Chart.yaml

```yaml
apiVersion: v2
name: mdbook-htmx
description: A Helm chart for mdbook-htmx documentation server
type: application
version: 1.0.0
appVersion: "0.1.0"
keywords:
- documentation
- mdbook
- htmx
maintainers:
- name: Your Name
email: you@example.com
dependencies:
- name: meilisearch
version: "0.5.x"
repository: "https://meilisearch.github.io/meilisearch-kubernetes"
condition: meilisearch.enabled
```

## values.yaml

```yaml
# Default values for mdbook-htmx

replicaCount: 3

image:
repository: nginx
pullPolicy: IfNotPresent
tag: "alpine"

imagePullSecrets: []
nameOverride: ""
fullnameOverride: ""

# Documentation source
docs:
# ConfigMap with docs content (created separately)
existingConfigMap: ""
# Or use PVC
persistence:
enabled: false
storageClass: ""
size: 1Gi
accessMode: ReadWriteOnce

# NGINX configuration
nginx:
# Custom nginx.conf
customConfig: ""
# Cache settings
cache:
enabled: true
staticMaxAge: "1y"
htmlMaxAge: "0"

serviceAccount:
create: true
annotations: {}
name: ""

podAnnotations: {}

podSecurityContext:
fsGroup: 101

securityContext:
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
runAsNonRoot: true
runAsUser: 101
capabilities:
drop:
- ALL

service:
type: ClusterIP
port: 80

ingress:
enabled: true
className: nginx
annotations:
cert-manager.io/cluster-issuer: letsencrypt-prod
hosts:
- host: docs.example.com
paths:
- path: /
pathType: Prefix
tls:
- secretName: docs-tls
hosts:
- docs.example.com

resources:
limits:
cpu: 200m
memory: 128Mi
requests:
cpu: 50m
memory: 64Mi

autoscaling:
enabled: true
minReplicas: 2
maxReplicas: 10
targetCPUUtilizationPercentage: 70
targetMemoryUtilizationPercentage: 80

pdb:
enabled: true
minAvailable: 1

nodeSelector: {}

tolerations: []

affinity:
podAntiAffinity:
preferredDuringSchedulingIgnoredDuringExecution:
- weight: 100
podAffinityTerm:
labelSelector:
matchLabels:
app.kubernetes.io/name: mdbook-htmx
topologyKey: kubernetes.io/hostname

# Meilisearch configuration
meilisearch:
enabled: false
auth:
existingMasterKeySecret: ""
persistence:
enabled: true
size: 5Gi
resources:
requests:
cpu: 100m
memory: 256Mi
limits:
cpu: 500m
memory: 512Mi

# Search indexer
indexer:
enabled: false
schedule: "0 */6 * * *"
image:
repository: python
tag: "3.11-slim"

# Monitoring
metrics:
enabled: false
serviceMonitor:
enabled: false
interval: 30s
```

## templates/_helpers.tpl

```yaml
{{/*
Expand the name of the chart.
*/}}
{{- define "mdbook-htmx.name" -}}
{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
{{- end }}

{{/*
Create a default fully qualified app name.
*/}}
{{- define "mdbook-htmx.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 }}

{{/*
Create chart name and version as used by the chart label.
*/}}
{{- define "mdbook-htmx.chart" -}}
{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
{{- end }}

{{/*
Common labels
*/}}
{{- define "mdbook-htmx.labels" -}}
helm.sh/chart: {{ include "mdbook-htmx.chart" . }}
{{ include "mdbook-htmx.selectorLabels" . }}
{{- if .Chart.AppVersion }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
{{- end }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}

{{/*
Selector labels
*/}}
{{- define "mdbook-htmx.selectorLabels" -}}
app.kubernetes.io/name: {{ include "mdbook-htmx.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}

{{/*
Service account name
*/}}
{{- define "mdbook-htmx.serviceAccountName" -}}
{{- if .Values.serviceAccount.create }}
{{- default (include "mdbook-htmx.fullname" .) .Values.serviceAccount.name }}
{{- else }}
{{- default "default" .Values.serviceAccount.name }}
{{- end }}
{{- end }}

{{/*
Meilisearch URL
*/}}
{{- define "mdbook-htmx.meilisearchUrl" -}}
{{- if .Values.meilisearch.enabled }}
{{- printf "http://%s-meilisearch:7700" .Release.Name }}
{{- else }}
{{- .Values.meilisearch.externalUrl | default "" }}
{{- end }}
{{- end }}
```

## templates/deployment.yaml

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ include "mdbook-htmx.fullname" . }}
labels:
{{- include "mdbook-htmx.labels" . | nindent 4 }}
spec:
{{- if not .Values.autoscaling.enabled }}
replicas: {{ .Values.replicaCount }}
{{- end }}
selector:
matchLabels:
{{- include "mdbook-htmx.selectorLabels" . | nindent 6 }}
template:
metadata:
annotations:
checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
{{- with .Values.podAnnotations }}
{{- toYaml . | nindent 8 }}
{{- end }}
labels:
{{- include "mdbook-htmx.selectorLabels" . | nindent 8 }}
spec:
{{- with .Values.imagePullSecrets }}
imagePullSecrets:
{{- toYaml . | nindent 8 }}
{{- end }}
serviceAccountName: {{ include "mdbook-htmx.serviceAccountName" . }}
securityContext:
{{- toYaml .Values.podSecurityContext | nindent 8 }}
containers:
- name: {{ .Chart.Name }}
securityContext:
{{- toYaml .Values.securityContext | nindent 12 }}
image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
imagePullPolicy: {{ .Values.image.pullPolicy }}
ports:
- name: http
containerPort: 80
protocol: TCP
livenessProbe:
httpGet:
path: /healthz
port: http
initialDelaySeconds: 5
periodSeconds: 10
readinessProbe:
httpGet:
path: /healthz
port: http
initialDelaySeconds: 5
periodSeconds: 5
resources:
{{- toYaml .Values.resources | nindent 12 }}
volumeMounts:
- name: nginx-config
mountPath: /etc/nginx/nginx.conf
subPath: nginx.conf
readOnly: true
- name: docs-content
mountPath: /usr/share/nginx/html
readOnly: true
- name: tmp
mountPath: /tmp
- name: cache
mountPath: /var/cache/nginx
- name: run
mountPath: /var/run
volumes:
- name: nginx-config
configMap:
name: {{ include "mdbook-htmx.fullname" . }}-nginx
- name: docs-content
{{- if .Values.docs.existingConfigMap }}
configMap:
name: {{ .Values.docs.existingConfigMap }}
{{- else if .Values.docs.persistence.enabled }}
persistentVolumeClaim:
claimName: {{ include "mdbook-htmx.fullname" . }}-docs
{{- else }}
emptyDir: {}
{{- end }}
- name: tmp
emptyDir: {}
- name: cache
emptyDir: {}
- name: run
emptyDir: {}
{{- with .Values.nodeSelector }}
nodeSelector:
{{- toYaml . | nindent 8 }}
{{- end }}
{{- with .Values.affinity }}
affinity:
{{- toYaml . | nindent 8 }}
{{- end }}
{{- with .Values.tolerations }}
tolerations:
{{- toYaml . | nindent 8 }}
{{- end }}
```

## Usage

### Install from local chart

```bash
# Create namespace
kubectl create namespace docs

# Create ConfigMap with docs content first
kubectl create configmap docs-content \
--from-file=book/ \
-n docs

# Install chart
helm install docs ./charts/mdbook-htmx \
--namespace docs \
--set docs.existingConfigMap=docs-content \
--set ingress.hosts[0].host=docs.example.com
```

### Install with Meilisearch

```bash
helm install docs ./charts/mdbook-htmx \
--namespace docs \
--set docs.existingConfigMap=docs-content \
--set meilisearch.enabled=true \
--set meilisearch.auth.existingMasterKeySecret=meilisearch-secrets \
--set indexer.enabled=true
```

### Upgrade

```bash
# Update docs content
kubectl create configmap docs-content \
--from-file=book/ \
-n docs \
--dry-run=client -o yaml | kubectl apply -f -

# Rollout restart to pick up new content
kubectl rollout restart deployment/docs -n docs
```

### Values override file

```yaml
# values-production.yaml
replicaCount: 5

ingress:
enabled: true
hosts:
- host: docs.mycompany.com
paths:
- path: /
pathType: Prefix
tls:
- secretName: docs-tls
hosts:
- docs.mycompany.com

meilisearch:
enabled: true
persistence:
size: 10Gi
resources:
limits:
cpu: 1000m
memory: 1Gi

autoscaling:
enabled: true
minReplicas: 3
maxReplicas: 20
```

```bash
helm install docs ./charts/mdbook-htmx \
--namespace docs \
-f values-production.yaml
```

## Publish to Chart Repository

```bash
# Package chart
helm package charts/mdbook-htmx

# Push to OCI registry
helm push mdbook-htmx-1.0.0.tgz oci://ghcr.io/org/charts

# Or add to Helm repo
helm repo add myrepo https://charts.example.com
helm push mdbook-htmx-1.0.0.tgz myrepo
```

## Next Steps

- Configure [Ingress authentication](./k8s-ingress-auth.md)
- Set up [GitHub Pages](./github-pages.md) for simpler deployments
- Use [Docker Compose](./docker-compose.md) for local development