Bernd RodlerandClaude Opus 4.8
eace443fdf
Fork of bulwarkmail/webmail for deploy on Vercel as project vncmail-plus. Adds vnc/ customization layer (branding, overrides, VNC-CHANGES log), Vercel env template, and VNCMAIL-SETUP.md runbook. No upstream files touched. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
67 lines
2.9 KiB
Markdown
67 lines
2.9 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` | 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`.)
|