# VNCmail+ — Vercel setup 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
`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

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