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	Tracks upstream Bulwark releases; kept as clean as possible
dev	VNC integration + Vercel production branch (for now)
vnc/*	Feature branches for UI work

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 = dev (move to main only when you cut a real prod domain).
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.

Syncing upstream later

git fetch upstream
git checkout main && git merge upstream/main   # bring in new Bulwark release
git checkout dev  && git merge main            # integrate; resolve via vnc/VNC-CHANGES.md
git push origin main dev                        # Vercel redeploys dev

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.)