Bernd RodlerandClaude Opus 4.8
83a9c5a809
Fix contradiction: production branch is main (Vercel default), dev auto-deploys previews, promote = ff-only merge dev→main on explicit go-live. Upstream synced into dev, not main. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
81 lines
3.6 KiB
Markdown
81 lines
3.6 KiB
Markdown
# 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` | **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`:
|
|
```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 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:
|
|
|
|
```bash
|
|
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`.)
|