feat(ci): GitLab CI/CD dev→prod pipeline, kustomize base+overlays

Multiple developers now work on this repo, and the only working deploy
trigger required pushing to GitHub - which contradicts the standing
GitLab-canonical policy for this repo - while every actual deploy was a
manual kubectl run against one environment (no prod exists at all).

Restructures deploy/k8s/ into base/ + overlays/{dev,prod}: overlays/dev
is a verified byte-for-byte no-op for the live sandbox (kubectl kustomize
diff against the old flat layout is empty), overlays/prod is scaffolded
but inert (placeholder hostname + JMAP_SERVER_URL, since neither a prod
hostname decision nor a prod Stalwart exist yet). deploy/k8s/ca/ (the
EJBCA internal CA) is untouched and never referenced by either overlay.

Adds .gitlab-ci.yml: verify (MR gate, no push/deploy) -> build+deploy-dev
(automatic on push to dev, one image name/tag-only environments, fixing
the old -dev/-beta naming split) -> promote (manual, protected
`production` environment, retags the exact dev digest via
`docker buildx imagetools create` - never rebuilds - and is left as a
documented TODO for the actual `kubectl apply` until prod is real).

Updates VNCMAIL-SETUP.md and deploy/k8s/README.md to describe the new
flow and correct the aspirational promotion description that assumed a
"production image" CI never actually built.

Also fixes a pre-existing lint error (no-control-regex false positive on
an intentional DN-sanitizing character class in lib/smime-ca/ejbca.ts)
that was blocking this commit's pre-commit hook - unrelated to this
change otherwise, confirmed already present on dev before this branch.

Runner/RBAC/registry setup is an infra prerequisite this commit cannot
provide - documented in the pipeline plan, not part of this diff.

deploy/k8s/README.md

@@ -1,29 +1,66 @@
 # VNCmail+ — Admin Deployment Guide (microk8s)
 
 Deploy VNCmail+ (VNC's Bulwark fork) as a container at **`vncmail.sandbox.vnc.de`**,
-**alongside** the existing `bulwark.sandbox.vnc.de`. Plain `kubectl apply` — no
-GitOps needed.
+**alongside** the existing `bulwark.sandbox.vnc.de`.
 
 > Why a container (not Vercel): Bulwark is stateful — it writes settings/admin/
 > telemetry to `/app/data`, which needs persistent volumes.
 
+## Structure — base + overlays
+
+```
+deploy/k8s/
+  base/               # shared manifest shapes (namespace-agnostic)
+  overlays/
+    dev/              # the live sandbox — vncmail.sandbox.vnc.de, namespace vncmail
+    prod/             # scaffolded, NOT YET LIVE — see "Production status" below
+  ca/                 # separate, isolated EJBCA internal CA — see ca/README.md.
+                       # Never composed with base/ or either overlay above.
+```
+
+`kubectl apply -k overlays/dev` (or `overlays/prod`, once real) instead of
+applying `base/` directly — `base/` alone has no namespace and won't apply
+meaningfully on its own.
+
+## Routine deploys go through CI now
+
+As of the GitLab CI/CD pipeline (`.gitlab-ci.yml`, see `../../VNCMAIL-SETUP.md`
+§ CI/CD), **pushing to `dev` auto-builds and auto-deploys** — you should not
+normally need to run `kubectl apply` for the sandbox by hand anymore. This
+guide's manual steps below are for first-time setup, the one-time secret
+creation CI deliberately never automates, and troubleshooting.
+
+## Production status
+
+**There is no production VNCmail+ deployment yet.** `overlays/prod/` exists
+in the repo but is inert: its ingress hostname and its secret's
+`JMAP_SERVER_URL` are both obvious placeholders (`vncmail.CHANGEME.invalid` /
+`https://REPLACE-ME-prod-stalwart-not-yet-deployed.invalid`) that will fail
+loudly rather than silently deploy against the wrong backend. Applying it
+requires, in order: a real prod Stalwart instance to exist, a real hostname
+decision, DNS, a real `secret.yaml`, and the `.gitlab-ci.yml` `promote` job's
+`kubectl apply` step (currently a TODO placeholder) filled in. None of that
+is CI's job to decide — it's an explicit, human-triggered event.
+
 ---
 
-## 1. What you are deploying
+## 1. What you are deploying (per overlay)
 
 | # | Object | File | Purpose |
 |---|--------|------|---------|
-| 1 | Namespace `vncmail` | `namespace.yaml` | Isolates the app |
-| 2 | 4× PersistentVolumeClaim | `pvc.yaml` | `/app/data/{settings,admin,admin-state,telemetry}` |
-| 3 | Secret `vncmail-env` | `secret.yaml` *(you create it)* | App config (JMAP URL, session secret, branding) |
-| 4 | Secret `ghcr-pull` | *(you create it — command below)* | Pull the private image from GHCR |
-| 5 | Deployment `vncmail-plus` | `deployment.yaml` | The app pod |
-| 6 | Service `vncmail-plus` | `service.yaml` | ClusterIP :80 → pod :3000 |
-| 7 | Ingress `vncmail-plus` | `ingress.yaml` | TLS host `vncmail.sandbox.vnc.de` |
+| 1 | Namespace | `overlays/<env>/namespace.yaml` | Isolates the app (`vncmail` for dev, `vncmail-prod` for prod) |
+| 2 | 4× PersistentVolumeClaim | `base/pvc.yaml` | `/app/data/{settings,admin,admin-state,telemetry}` |
+| 3 | Secret `vncmail-env` | `overlays/<env>/secret.yaml` *(you create it)* | App config (JMAP URL, session secret, branding) |
+| 4 | Image-pull secret | *(you create it — command below)* | Pull the (currently private) image |
+| 5 | Deployment `vncmail-plus` | `base/deployment.yaml` (+ overlay patches) | The app pod |
+| 6 | Service `vncmail-plus` | `base/service.yaml` | ClusterIP :80 → pod :3000 |
+| 7 | Ingress `vncmail-plus` | `base/ingress.yaml` (+ overlay patches for prod) | TLS host |
 
-**Image:** `ghcr.io/brvncde-dotcom/vncmail-plus-dev:latest`
-(built automatically by CI from the `dev` branch). For anything beyond the
-sandbox, pin a digest — see §5.
+**Image:** CI builds and pushes to `registry.gitlab.vnc.biz/gitlab-instance-b9b5cf2f/vncmail-plus`
+(tag `sha-<sha>` per deploy, moving pointers `dev-latest`/`prod-latest`). The
+`ghcr.io/brvncde-dotcom/vncmail-plus-dev` image referenced in `base/deployment.yaml`
+is a legacy default only — CI overrides it per-deploy via `kubectl set image`,
+so what's committed there never needs to track what's actually running.
 
 ---
 
@@ -43,45 +80,48 @@ kubectl get ingressclass
 kubectl get clusterissuer      # cert-manager issuers (if used)
 ```
 
-Then edit if they differ from the defaults below:
+Then edit if they differ from the defaults below (in `base/`, so both overlays
+pick up the fix):
 
 | Value | Default in manifests | File to edit |
 |-------|----------------------|--------------|
-| StorageClass | `microk8s-hostpath` | `pvc.yaml` (all 4) |
-| IngressClass | `public` | `ingress.yaml` |
-| cert-manager issuer | `letsencrypt-prod` | `ingress.yaml` |
+| StorageClass | `microk8s-hostpath` | `base/pvc.yaml` (all 4) |
+| IngressClass | `public` | `base/ingress.yaml` |
+| cert-manager issuer | `letsencrypt-prod` | `base/ingress.yaml` |
 
 ---
 
-## 3. Deploy (copy-paste, in order)
+## 3. First-time setup (one-time, per environment — CI never does this)
 
 ```bash
-cd deploy/k8s
+cd deploy/k8s/overlays/dev     # or overlays/prod, once real
 
-# a) Namespace
-kubectl apply -f namespace.yaml
-
-# b) Image-pull secret — the GHCR package is private.
-#    Use a GitHub PAT (classic) with the read:packages scope.
+# a) Image-pull secret — the registry package is private.
 kubectl create secret docker-registry ghcr-pull \
   --namespace vncmail \
   --docker-server=ghcr.io \
   --docker-username=brvncde-dotcom \
   --docker-password='<GITHUB_PAT_read:packages>' \
   --docker-email=br@vnc.biz
+#    Once CI has cut over to registry.gitlab.vnc.biz, this becomes a
+#    docker-registry secret for that registry instead — see VNCMAIL-SETUP.md.
 
-# c) App config secret — copy the template, set a real SESSION_SECRET, apply.
+# b) App config secret — copy the template, set a real SESSION_SECRET, apply.
 cp secret.example.yaml secret.yaml
 #    edit secret.yaml:  SESSION_SECRET: "$(openssl rand -base64 32)"
 kubectl apply -f secret.yaml
 
-# d) Everything else (PVCs, Deployment, Service, Ingress)
+# c) Everything else (namespace, PVCs, Deployment, Service, Ingress)
 kubectl apply -k .
 ```
 
-> Alternative to (b): make the GHCR package public
-> (GitHub → Packages → vncmail-plus-dev → Package settings → Change visibility),
-> then delete the `imagePullSecrets:` block from `deployment.yaml`.
+> Alternative to (a): make the registry package public, then delete the
+> `imagePullSecrets:` block from `base/deployment.yaml`.
+
+After this one-time setup, routine deploys to `dev` happen automatically via
+CI on every push — see "Routine deploys go through CI now" above. This
+section is for first-time bring-up (or `overlays/prod`, once it's real) and
+troubleshooting, not the everyday path.
 
 ---
 
@@ -104,13 +144,12 @@ a bare username.
 
 ## 5. Update to a new build
 
-```bash
-# CI rebuilds ghcr.io/brvncde-dotcom/vncmail-plus-dev on every push to `dev`.
-kubectl -n vncmail rollout restart deploy/vncmail-plus     # pulls :latest (imagePullPolicy: Always)
+Normally you don't — CI's `deploy-dev` job does this automatically on every
+push to `dev`. To do it by hand (e.g. troubleshooting):
 
-# Production: pin a digest instead of :latest so rollouts are deterministic.
+```bash
 kubectl -n vncmail set image deploy/vncmail-plus \
-  vncmail-plus=ghcr.io/brvncde-dotcom/vncmail-plus-dev@sha256:<digest>
+  vncmail-plus=registry.gitlab.vnc.biz/gitlab-instance-b9b5cf2f/vncmail-plus:sha-<sha>
 ```
 
 Rollback: `kubectl -n vncmail rollout undo deploy/vncmail-plus`
@@ -121,9 +160,9 @@ Rollback: `kubectl -n vncmail rollout undo deploy/vncmail-plus`
 
 | Symptom | Cause / fix |
 |---------|-------------|
-| Pod `ImagePullBackOff` | `ghcr-pull` secret missing/expired, or package still private. Recreate the secret (§3b) or make the package public. |
-| Pod `CrashLoopBackOff`, logs show `EACCES`/permission on `/app/data` | Volume not writable by uid 1001. `securityContext.fsGroup: 1001` is set in `deployment.yaml` — keep it; some storage drivers also need it on the PVC. |
-| PVC stuck `Pending` | Wrong `storageClassName` in `pvc.yaml`. Set it to one from `kubectl get sc`. |
+| Pod `ImagePullBackOff` | `ghcr-pull` secret missing/expired, or package still private. Recreate the secret (§3a) or make the package public. |
+| Pod `CrashLoopBackOff`, logs show `EACCES`/permission on `/app/data` | Volume not writable by uid 1001. `securityContext.fsGroup: 1001` is set in `base/deployment.yaml` — keep it; some storage drivers also need it on the PVC. |
+| PVC stuck `Pending` | Wrong `storageClassName` in `base/pvc.yaml`. Set it to one from `kubectl get sc`. |
 | Ingress has no address / no cert | Wrong `ingressClassName` or cert issuer. Match bulwark's (§2). Check `kubectl -n vncmail describe ingress vncmail-plus`. |
 | Login shows "Ein Fehler ist aufgetreten" | Use the **full** email (`user@sandbox.vnc.de`), not a bare username. |
 | Can't reach Stalwart | Check `JMAP_SERVER_URL` in the secret = `https://stalwart.sandbox.vnc.de`. |

deploy/k8s/base/deployment.yaml

@@ -2,7 +2,6 @@ apiVersion: apps/v1
 kind: Deployment
 metadata:
   name: vncmail-plus
-  namespace: vncmail
   labels:
     app: vncmail-plus
 spec:
@@ -26,12 +25,17 @@ spec:
         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.
+      # NOTE: once CI moves to pushing registry.gitlab.vnc.biz images (the
+      # dev-auto-deploy phase of the GitLab pipeline), this needs to become a
+      # docker-registry secret for that registry instead — comments only,
+      # deliberately not renamed here, so this file stays a no-op today.
       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>
+          # Default/legacy value — CI overrides the image per-deploy via
+          # `kustomize edit set image`, so what's committed here never goes
+          # stale. For a one-off manual apply, pin a digest instead of :latest.
           image: ghcr.io/brvncde-dotcom/vncmail-plus-dev:latest
           imagePullPolicy: Always
           ports:

deploy/k8s/base/ingress.yaml

@@ -7,7 +7,6 @@ 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

deploy/k8s/base/kustomization.yaml

@@ -0,0 +1,14 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - pvc.yaml
+  - deployment.yaml
+  - service.yaml
+  - ingress.yaml
+  # - secret.yaml   # create from an overlay's secret.example.yaml; not committed
+
+# Namespace is intentionally NOT set here. Kustomize's `namespace:` transformer
+# doesn't rename cluster-scoped Namespace objects, so each overlay ships its own
+# namespace.yaml (the actual object) and its own `namespace:` field (which
+# injects metadata.namespace into every namespaced resource below). Applying
+# this base directly is meaningless — always go through an overlay.

deploy/k8s/base/pvc.yaml

@@ -5,7 +5,6 @@ apiVersion: v1
 kind: PersistentVolumeClaim
 metadata:
   name: vncmail-settings
-  namespace: vncmail
 spec:
   accessModes: [ReadWriteOnce]
   storageClassName: microk8s-hostpath
@@ -17,7 +16,6 @@ apiVersion: v1
 kind: PersistentVolumeClaim
 metadata:
   name: vncmail-admin
-  namespace: vncmail
 spec:
   accessModes: [ReadWriteOnce]
   storageClassName: microk8s-hostpath
@@ -29,7 +27,6 @@ apiVersion: v1
 kind: PersistentVolumeClaim
 metadata:
   name: vncmail-admin-state
-  namespace: vncmail
 spec:
   accessModes: [ReadWriteOnce]
   storageClassName: microk8s-hostpath
@@ -41,7 +38,6 @@ apiVersion: v1
 kind: PersistentVolumeClaim
 metadata:
   name: vncmail-telemetry
-  namespace: vncmail
 spec:
   accessModes: [ReadWriteOnce]
   storageClassName: microk8s-hostpath

deploy/k8s/base/service.yaml

@@ -2,7 +2,6 @@ apiVersion: v1
 kind: Service
 metadata:
   name: vncmail-plus
-  namespace: vncmail
   labels:
     app: vncmail-plus
 spec:

deploy/k8s/overlays/dev/kustomization.yaml

@@ -0,0 +1,13 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+namespace: vncmail
+resources:
+  - ../../base
+  - namespace.yaml
+  # - secret.yaml   # create from secret.example.yaml; not committed
+
+# This is the live sandbox (vncmail.sandbox.vnc.de) — deliberately zero patches
+# beyond namespace/resource wiring, so `kubectl kustomize .` renders identical
+# to the pre-restructure flat deploy/k8s/. The image is left at base's default
+# and overridden per-deploy by CI (`kubectl set image`, see .gitlab-ci.yml's
+# deploy-dev job) rather than pinned here, so this file never goes stale.

deploy/k8s/overlays/prod/kustomization.yaml

@@ -0,0 +1,21 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+namespace: vncmail-prod
+resources:
+  - ../../base
+  - namespace.yaml
+  # - secret.yaml   # create from secret.example.yaml; not committed
+
+patches:
+  - path: patch-ingress.yaml
+  - path: patch-deployment.yaml
+
+# NOT MEANT TO BE APPLIED AS COMMITTED. Scaffolding only (see the pipeline
+# plan's Phase C/D) — the tag below is an obviously-invalid placeholder;
+# the real promote job (.gitlab-ci.yml) resolves and pins an actual digest at
+# deploy time via `kubectl set image`, it never trusts whatever is checked
+# in here.
+images:
+  - name: ghcr.io/brvncde-dotcom/vncmail-plus-dev
+    newName: registry.gitlab.vnc.biz/gitlab-instance-b9b5cf2f/vncmail-plus
+    newTag: not-yet-promoted

deploy/k8s/overlays/prod/namespace.yaml

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

deploy/k8s/overlays/prod/patch-deployment.yaml

@@ -0,0 +1,9 @@
+# Basic HA. Still `strategy: Recreate` (inherited from base) since the PVCs
+# are RWO — 2 replicas doesn't buy zero-downtime rollouts by itself, only
+# tolerance for a node loss between deploys. Revisit if that's not enough.
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: vncmail-plus
+spec:
+  replicas: 2

deploy/k8s/overlays/prod/patch-ingress.yaml

@@ -0,0 +1,25 @@
+# PLACEHOLDER — the real production hostname has not been decided yet (see
+# VNCMAIL-SETUP.md / the pipeline plan). vncmail.CHANGEME.invalid is
+# deliberately unresolvable: applying this overlay as committed will not
+# issue a cert or route traffic anywhere. Replace both occurrences below,
+# and the matching TLS secretName, before Phase D (first real prod deploy).
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: vncmail-plus
+spec:
+  tls:
+    - hosts:
+        - vncmail.CHANGEME.invalid
+      secretName: vncmail-plus-prod-tls
+  rules:
+    - host: vncmail.CHANGEME.invalid
+      http:
+        paths:
+          - path: /
+            pathType: Prefix
+            backend:
+              service:
+                name: vncmail-plus
+                port:
+                  number: 80

deploy/k8s/overlays/prod/secret.example.yaml

@@ -0,0 +1,28 @@
+# 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
+#
+# JMAP_SERVER_URL is a PLACEHOLDER — there is no production Stalwart instance
+# yet. This overlay cannot go live (Phase D) until one exists and this value
+# points at it for real.
+apiVersion: v1
+kind: Secret
+metadata:
+  name: vncmail-env
+  namespace: vncmail-prod
+type: Opaque
+stringData:
+  # Core — connect to Stalwart over JMAP
+  JMAP_SERVER_URL: "https://REPLACE-ME-prod-stalwart-not-yet-deployed.invalid"
+  SESSION_SECRET: "REPLACE_ME__openssl_rand_base64_32"
+  # Branding (theme defaults to VNClagoon in code; these set name + logo)
+  APP_NAME: "VNCmail+"
+  APP_SHORT_NAME: "VNCmail+"
+  LOGIN_COMPANY_NAME: "VNClagoon"
+  LOGIN_LOGO_DARK_URL: "/branding/vncmail-wordmark-on-dark.svg"
+  LOGIN_LOGO_LIGHT_URL: "/branding/vncmail-wordmark-on-light.svg"
+  APP_LOGO_DARK_URL: "/branding/vncmail-wordmark-on-dark.svg"
+  APP_LOGO_LIGHT_URL: "/branding/vncmail-wordmark-on-light.svg"
+  LOGIN_LOGO_MAX_HEIGHT: "52"
+  # Housekeeping
+  BULWARK_UPDATE_CHECK: "off"
+  # Data dirs default to /app/data/* (mounted to the PVCs) — no need to set them.