feat(deploy): k8s manifests for microk8s (vncmail.sandbox.vnc.de)

Bulwark is stateful (local /app/data) — Vercel serverless (read-only fs)
crashes it. Deploy as a container with 4 persistent volumes on microk8s,
alongside bulwark.sandbox.vnc.de. Adds deploy/k8s/ (namespace, pvc, deployment,
service, ingress, secret template, runbook) + rewrites setup doc off Vercel.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.gitignore

@@ -50,3 +50,6 @@ next-env.d.ts
 
 # Sibling repos
 /repos/
+
+# k8s deploy secret (create from deploy/k8s/secret.example.yaml)
+/deploy/k8s/secret.yaml

VNCMAIL-SETUP.md

@@ -1,71 +1,67 @@
-# VNCmail+ — Vercel setup runbook
+# VNCmail+ — setup & deploy runbook
 
 VNCmail+ is VNC's fork of [Bulwark](https://github.com/bulwarkmail/webmail), a
 Next.js (App Router) JMAP webmail client for **Stalwart**. Stalwart is the source
-of truth; VNCmail+ is the UI. This repo deploys to **Vercel** as project
+of truth; VNCmail+ is the UI. It deploys as a **container on Kubernetes
-`vncmail-plus`.
+(microk8s)** at `vncmail.sandbox.vnc.de` — see **[deploy/k8s/](deploy/k8s/README.md)**.
 
 > **License:** AGPL-3.0. Serving a modified VNCmail+ to users over the network
 > obligates VNC to offer those users the corresponding source. Keeping this fork
 > public (with a "Source" link in the imprint/UI) satisfies that. Loop in legal
 > before a public/customer-facing launch if a closed fork is ever desired.
 
-## Architecture (why Vercel works here)
+## Architecture — why a container, not Vercel
 
-- JMAP calls go through **server-side Next.js `/api/*` routes** (see `proxy.ts`),
+- Bulwark is a **stateful, long-lived server**: it persists settings-sync, admin
-  i.e. Vercel Functions talk to Stalwart server-to-server → **no browser CORS**.
+  config/state, and telemetry to a **local data directory** (`/app/data/*`).
-- Config is **runtime-read**, so env changes don't need a rebuild.
+- **Vercel serverless was tried and dropped** — its filesystem is read-only
-- Real data (mail/calendar/contacts) lives in **Stalwart**, so Vercel's
+  except `/tmp`, so Bulwark's `mkdir ./data` crashes (`ENOENT /var/task/data`).
-  ephemeral filesystem is fine. The only features that want a persistent disk
+  You cannot point its data dirs at a remote host either (they're POSIX paths,
-  (settings-sync, admin-dashboard persistence, telemetry) are **off by default**
+  not URLs). Bulwark's native model is a container + persistent volumes.
-  and left off here. If VNC ever needs those persisted, host the upstream Docker
+- So VNCmail+ runs as a Docker image (`ghcr.io/brvncde-dotcom/vncmail-plus-*`)
-  image on VNC infra instead of / alongside Vercel.
+  with **4 persistent volumes**, exactly like the existing `bulwark.sandbox.vnc.de`.
+- JMAP calls go through **server-side `/api/*` routes** (`proxy.ts`) → server-to-
+  server to Stalwart, **no browser CORS**. Config is **runtime-read**.
 
 ## Branches (dev-first)
 
 | Branch | Role |
 |--------|------|
-| `main` | **Production** — Vercel production branch. Only updated by an explicit promote. |
+| `main` | **Production** — CI builds `…/vncmail-plus-beta`. Only updated by an explicit promote. |
-| `dev`  | Integration + QA — every push auto-deploys a Vercel **preview**. Default working branch. |
+| `dev`  | Integration + QA — CI builds `…/vncmail-plus-dev` on push. Default working branch. |
 | `vnc/*`| Feature branches for UI work (branch off `dev`, PR into `dev`). |
 
 All VNC customization lives under `vnc/` (see `vnc/VNC-CHANGES.md`).
 
-## One-time Vercel setup
+## Deploy (Kubernetes / microk8s)
 
-1. **New Project** → import `brvncde-dotcom/vncmail-plus`.
+Full runbook: **[deploy/k8s/README.md](deploy/k8s/README.md)**. In short:
-2. Project name: **`vncmail-plus`** (display "VNCmail+"). Framework: Next.js (auto).
-3. **Settings → Git → Production Branch = `main`** (Vercel's default for this repo).
-   `dev` and `vnc/*` pushes deploy as previews.
-4. **Settings → Environment Variables:** paste from `vnc/vercel.env.template`.
-   - Generate the secret: `openssl rand -base64 32`
-   - Mark `SESSION_SECRET` as **Sensitive**.
-5. **Deploy.** Then open the deployment URL and log in as a
-   `@sandbox.vnc.de` test user (anyone in `vncdirectory.sandbox.vnc.de`).
 
-## Custom domain (recommended)
+1. CI builds the image on push to `dev`/`main` → `ghcr.io/brvncde-dotcom/vncmail-plus-dev` (`.github/workflows/docker-publish.yml`).
+2. `kubectl apply` the manifests in `deploy/k8s/` (namespace, 4 PVCs, deployment, service, ingress) + a `secret.yaml` (from `secret.example.yaml`) + a `ghcr-pull` image-pull secret.
+3. Point `vncmail.sandbox.vnc.de` DNS at the ingress; cert-manager issues TLS.
 
-Add a subdomain of the Stalwart parent, e.g. `mail.sandbox.vnc.de` or
+Runs alongside the existing `bulwark.sandbox.vnc.de`. Match your cluster's
-`vncmailplus.sandbox.vnc.de`, in Vercel → Domains. Same parent domain keeps
+StorageClass / IngressClass / cert issuer to bulwark's (see the runbook).
-everything tidy and avoids any future cross-origin edge cases.
 
 ## Deploy workflow (dev-first — ALWAYS)
 
 Same flow as every other VNC/SRC repo:
 
-1. Work on `dev` (or `vnc/*` → PR into `dev`). Every push to `dev` auto-deploys a **preview**. QA there.
+1. Work on `dev` (or `vnc/*` → PR into `dev`). Push to `dev` → CI builds the `-dev` image → `kubectl -n vncmail rollout restart deploy/vncmail-plus` to pull it. QA at `vncmail.sandbox.vnc.de`.
 2. **Promote to production only on explicit go-live** — merge `dev` → `main`:
    ```bash
    git log dev..main            # MUST be empty — main must have nothing dev lacks (else prod would revert)
    git checkout main && git merge --ff-only dev
-   git push origin main         # Vercel deploys main → production
+   git push origin main         # CI builds the production image
    git checkout dev
    ```
+   Then roll the production deployment to the new image (pin its digest — see deploy/k8s/README.md).
    Never push straight to `main`. Never let a dev→main merge silently revert prod.
 
 ## Syncing upstream (Bulwark releases)
 
-Bring upstream into `dev` (NOT main), integrate on a preview, then promote as above:
+Bring upstream into `dev` (NOT main), integrate + QA on the dev image, then promote as above:
 
 ```bash
 git fetch upstream

deploy/k8s/README.md

@@ -0,0 +1,88 @@
+# VNCmail+ on Kubernetes (microk8s)
+
+Deploys the VNCmail+ fork as a **new subdomain** (`vncmail.sandbox.vnc.de`),
+alongside the existing `bulwark.sandbox.vnc.de`. This is Bulwark's native model:
+a long-lived container + persistent volumes. (Vercel was dropped — its serverless
+filesystem is read-only, which crashes Bulwark's disk-backed features.)
+
+## Image
+
+CI builds and pushes the image on every push to `dev`/`main`
+(`.github/workflows/docker-publish.yml`):
+
+- `dev`  → `ghcr.io/brvncde-dotcom/vncmail-plus-dev`
+- `main` → `ghcr.io/brvncde-dotcom/vncmail-plus-beta`
+- release tag → `ghcr.io/brvncde-dotcom/vncmail-plus` (clean name)
+
+The manifests use the `-dev` image. **For production, pin a digest** instead of
+`:latest`:
+```
+kubectl -n vncmail set image deploy/vncmail-plus \
+  vncmail-plus=ghcr.io/brvncde-dotcom/vncmail-plus-dev@sha256:<digest>
+```
+
+## Prerequisites — match your cluster
+
+These manifests use microk8s defaults; confirm they match how
+`bulwark.sandbox.vnc.de` is deployed and edit if not:
+
+| Thing | File | Check with |
+|-------|------|-----------|
+| StorageClass (`microk8s-hostpath`) | `pvc.yaml` | `kubectl get sc` |
+| IngressClass (`public`) | `ingress.yaml` | `kubectl get ingressclass` |
+| cert-manager issuer (`letsencrypt-prod`) | `ingress.yaml` | `kubectl get clusterissuer` + bulwark's ingress |
+
+Quickest: copy bulwark's own settings —
+`kubectl get ingress -A | grep bulwark` then `kubectl get ingress <name> -n <ns> -o yaml`.
+
+## Deploy
+
+```bash
+# 1. Namespace
+kubectl apply -f namespace.yaml
+
+# 2. GHCR pull secret (package is private by default).
+#    Use a GitHub PAT with read:packages.
+kubectl create secret docker-registry ghcr-pull \
+  --namespace vncmail \
+  --docker-server=ghcr.io \
+  --docker-username=brvncde-dotcom \
+  --docker-password=<GITHUB_PAT_with_read:packages> \
+  --docker-email=br@vnc.biz
+#    (Or make the package public in GHCR and remove imagePullSecrets from deployment.yaml.)
+
+# 3. App config secret
+cp secret.example.yaml secret.yaml
+#    edit secret.yaml → set SESSION_SECRET (openssl rand -base64 32)
+kubectl apply -f secret.yaml
+
+# 4. Everything else
+kubectl apply -k .        # kustomization: pvc, deployment, service, ingress
+
+# 5. Watch it come up
+kubectl -n vncmail rollout status deploy/vncmail-plus
+kubectl -n vncmail get pods,ingress
+```
+
+## DNS
+
+Point `vncmail.sandbox.vnc.de` at the same ingress load-balancer IP as
+`bulwark.sandbox.vnc.de` (A/AAAA or CNAME). cert-manager issues the TLS cert
+once DNS resolves.
+
+## Verify
+
+```bash
+curl -sI https://vncmail.sandbox.vnc.de/api/health     # expect 200
+```
+Then open `https://vncmail.sandbox.vnc.de` and log in with a full
+`@sandbox.vnc.de` address (e.g. `bernd.rodler@sandbox.vnc.de`) — Stalwart
+authenticates the **full email**, not a bare username.
+
+## Update after a UI change
+
+```bash
+git push origin dev                 # CI rebuilds ghcr.io/...-dev
+kubectl -n vncmail rollout restart deploy/vncmail-plus   # pull new image
+```
+Promote to production the usual dev-first way (see ../../VNCMAIL-SETUP.md).

deploy/k8s/deployment.yaml

@@ -0,0 +1,87 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: vncmail-plus
+  namespace: vncmail
+  labels:
+    app: vncmail-plus
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: vncmail-plus
+  # RWO volumes can only mount to one pod — Recreate avoids a stuck rollout.
+  strategy:
+    type: Recreate
+  template:
+    metadata:
+      labels:
+        app: vncmail-plus
+    spec:
+      # The image runs as uid/gid 1001 (nextjs:nodejs) and the Dockerfile
+      # chowns /app/data to 1001. fsGroup makes the mounted PVCs writable by it.
+      securityContext:
+        fsGroup: 1001
+        runAsUser: 1001
+        runAsGroup: 1001
+      # ghcr package is private by default — see deploy/k8s/README.md to create
+      # this pull secret. Delete this block if you make the package public.
+      imagePullSecrets:
+        - name: ghcr-pull
+      containers:
+        - name: vncmail-plus
+          # dev image (built from the `dev` branch by CI). For production pin a
+          # digest: ghcr.io/brvncde-dotcom/vncmail-plus-dev@sha256:<digest>
+          image: ghcr.io/brvncde-dotcom/vncmail-plus-dev:latest
+          imagePullPolicy: Always
+          ports:
+            - containerPort: 3000
+          envFrom:
+            - secretRef:
+                name: vncmail-env
+          env:
+            - name: HOSTNAME
+              value: "0.0.0.0"
+            - name: PORT
+              value: "3000"
+          readinessProbe:
+            httpGet:
+              path: /api/health
+              port: 3000
+            initialDelaySeconds: 10
+            periodSeconds: 10
+          livenessProbe:
+            httpGet:
+              path: /api/health
+              port: 3000
+            initialDelaySeconds: 25
+            periodSeconds: 30
+          resources:
+            requests:
+              cpu: 100m
+              memory: 256Mi
+            limits:
+              cpu: "1"
+              memory: 1Gi
+          volumeMounts:
+            - name: settings
+              mountPath: /app/data/settings
+            - name: admin
+              mountPath: /app/data/admin
+            - name: admin-state
+              mountPath: /app/data/admin-state
+            - name: telemetry
+              mountPath: /app/data/telemetry
+      volumes:
+        - name: settings
+          persistentVolumeClaim:
+            claimName: vncmail-settings
+        - name: admin
+          persistentVolumeClaim:
+            claimName: vncmail-admin
+        - name: admin-state
+          persistentVolumeClaim:
+            claimName: vncmail-admin-state
+        - name: telemetry
+          persistentVolumeClaim:
+            claimName: vncmail-telemetry

deploy/k8s/ingress.yaml

@@ -0,0 +1,34 @@
+# Exposes VNCmail+ at vncmail.sandbox.vnc.de, alongside bulwark.sandbox.vnc.de.
+# MATCH YOUR CLUSTER — inspect the existing Bulwark ingress and copy its
+# ingressClassName + TLS/cert-manager annotations:
+#   kubectl get ingress -A | grep bulwark
+#   kubectl get ingress <bulwark-ingress> -n <ns> -o yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: vncmail-plus
+  namespace: vncmail
+  annotations:
+    # cert-manager issuer — set to whatever bulwark.sandbox.vnc.de uses.
+    cert-manager.io/cluster-issuer: letsencrypt-prod
+    # Mail attachments can be large; raise the nginx body limit.
+    nginx.ingress.kubernetes.io/proxy-body-size: "100m"
+spec:
+  # microk8s ingress addon class is usually "public" (nginx). Confirm with
+  # `kubectl get ingressclass` and match bulwark's.
+  ingressClassName: public
+  tls:
+    - hosts:
+        - vncmail.sandbox.vnc.de
+      secretName: vncmail-plus-tls
+  rules:
+    - host: vncmail.sandbox.vnc.de
+      http:
+        paths:
+          - path: /
+            pathType: Prefix
+            backend:
+              service:
+                name: vncmail-plus
+                port:
+                  number: 80

deploy/k8s/kustomization.yaml

@@ -0,0 +1,10 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+namespace: vncmail
+resources:
+  - namespace.yaml
+  - pvc.yaml
+  - deployment.yaml
+  - service.yaml
+  - ingress.yaml
+  # - secret.yaml   # create from secret.example.yaml; not committed

deploy/k8s/namespace.yaml

@@ -0,0 +1,6 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: vncmail
+  labels:
+    app.kubernetes.io/part-of: vnclagoon-suite

deploy/k8s/pvc.yaml

@@ -0,0 +1,50 @@
+# Four persistent volumes — mirror the fork's docker-compose volumes.
+# storageClassName: microk8s default is "microk8s-hostpath". Match your
+# cluster: `kubectl get sc`. Change all four if yours differs.
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: vncmail-settings
+  namespace: vncmail
+spec:
+  accessModes: [ReadWriteOnce]
+  storageClassName: microk8s-hostpath
+  resources:
+    requests:
+      storage: 1Gi
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: vncmail-admin
+  namespace: vncmail
+spec:
+  accessModes: [ReadWriteOnce]
+  storageClassName: microk8s-hostpath
+  resources:
+    requests:
+      storage: 256Mi
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: vncmail-admin-state
+  namespace: vncmail
+spec:
+  accessModes: [ReadWriteOnce]
+  storageClassName: microk8s-hostpath
+  resources:
+    requests:
+      storage: 256Mi
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: vncmail-telemetry
+  namespace: vncmail
+spec:
+  accessModes: [ReadWriteOnce]
+  storageClassName: microk8s-hostpath
+  resources:
+    requests:
+      storage: 256Mi

deploy/k8s/secret.example.yaml

@@ -0,0 +1,19 @@
+# Copy to secret.yaml, fill in real values, and apply. DO NOT commit secret.yaml
+# (it is gitignored). Generate SESSION_SECRET with:  openssl rand -base64 32
+apiVersion: v1
+kind: Secret
+metadata:
+  name: vncmail-env
+  namespace: vncmail
+type: Opaque
+stringData:
+  # Core — connect to Stalwart over JMAP
+  JMAP_SERVER_URL: "https://stalwart.sandbox.vnc.de"
+  SESSION_SECRET: "REPLACE_ME__openssl_rand_base64_32"
+  # Branding
+  APP_NAME: "VNCmail+"
+  APP_SHORT_NAME: "VNCmail+"
+  LOGIN_COMPANY_NAME: "VNC"
+  # Housekeeping
+  BULWARK_UPDATE_CHECK: "off"
+  # Data dirs default to /app/data/* (mounted to the PVCs) — no need to set them.

deploy/k8s/service.yaml

@@ -0,0 +1,14 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: vncmail-plus
+  namespace: vncmail
+  labels:
+    app: vncmail-plus
+spec:
+  selector:
+    app: vncmail-plus
+  ports:
+    - name: http
+      port: 80
+      targetPort: 3000

vnc/VNC-CHANGES.md

@@ -23,6 +23,14 @@ that merging new upstream releases stays a triage exercise, not an archaeology d
 | 2026-08-03 | `vnc/` (new) | Added VNC customization dir + this log | Fork bootstrap |
 | 2026-08-03 | `VNCMAIL-SETUP.md` (new) | Vercel deploy runbook | Deploy on Vercel as project "VNCmail+" |
 
-_Note: a microfrontends integration (next.config wrap + `@vercel/microfrontends`) was added and then **reverted** on 2026-08-03 — VNCmail+ is a standalone project, grouped organizationally via a separate Vercel team, not a microfrontends group._
+| 2026-08-03 | `deploy/k8s/` (new) | k8s manifests + runbook for microk8s deploy | Bulwark is stateful → runs as a container w/ persistent volumes, not Vercel serverless |
+| 2026-08-03 | `.gitignore` | ignore `deploy/k8s/secret.yaml` | keep the real env secret out of git |
+
+_Note: Vercel was tried and **abandoned** on 2026-08-03. Bulwark writes to a local
+data dir (`/app/data/*`); Vercel serverless has a read-only filesystem → crash
+(`ENOENT /var/task/data`). VNCmail+ now deploys as a Docker image
+(`ghcr.io/brvncde-dotcom/vncmail-plus-*`) on Kubernetes (microk8s) at
+`vncmail.sandbox.vnc.de`, with 4 persistent volumes — see `deploy/k8s/`. A
+microfrontends integration was also added and reverted the same day._
 
 _(append new rows as you diverge)_