SRCmail/VNCMAIL-SETUP.md

VNCmail+ — Vercel setup runbook

VNCmail+ is VNC's fork of Bulwark, 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 vncmail-plus.

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)

• JMAP calls go through server-side Next.js /api/* routes (see proxy.ts), i.e. Vercel Functions talk to Stalwart server-to-server → no browser CORS.
• Config is runtime-read, so env changes don't need a rebuild.
• Real data (mail/calendar/contacts) lives in Stalwart, so Vercel's ephemeral filesystem is fine. The only features that want a persistent disk (settings-sync, admin-dashboard persistence, telemetry) are off by default and left off here. If VNC ever needs those persisted, host the upstream Docker image on VNC infra instead of / alongside Vercel.

Branches (dev-first)

Branch	Role
main	Production — Vercel production branch. Only updated by an explicit promote.
dev	Integration + QA — every push auto-deploys a Vercel preview. 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

1. New Project → import brvncde-dotcom/vncmail-plus.
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)

Add a subdomain of the Stalwart parent, e.g. mail.sandbox.vnc.de or vncmailplus.sandbox.vnc.de, in Vercel → Domains. Same parent domain keeps 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.
2. Promote to production only on explicit go-live — merge dev → main:

   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 checkout dev
   

   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:

git fetch upstream
git checkout dev && git merge upstream/main    # resolve conflicts via vnc/VNC-CHANGES.md; QA on preview

Auth

Basic auth via Stalwart is the default — users sign in with their @sandbox.vnc.de address + password; VNCmail+ authenticates them over JMAP. No extra config. (SSO via vncdirectory/OIDC is a later option — see vnc/vercel.env.template.)