diff --git a/VNCMAIL-SETUP.md b/VNCMAIL-SETUP.md new file mode 100644 index 00000000..0c5407fb --- /dev/null +++ b/VNCMAIL-SETUP.md @@ -0,0 +1,66 @@ +# 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`.) diff --git a/vnc/VNC-CHANGES.md b/vnc/VNC-CHANGES.md new file mode 100644 index 00000000..ce2bc919 --- /dev/null +++ b/vnc/VNC-CHANGES.md @@ -0,0 +1,26 @@ +# VNC-CHANGES — VNCmail+ divergence log + +VNCmail+ is a fork of [bulwarkmail/webmail](https://github.com/bulwarkmail/webmail) +(AGPL-3.0). This file records **every** intentional divergence from upstream so +that merging new upstream releases stays a triage exercise, not an archaeology dig. + +## Rules of the fork + +1. **Keep upstream files unmodified whenever possible.** Prefer env vars + (branding), the `vnc/overrides/` layer, and additive files over editing files + inside `app/`, `components/`, `lib/`, `stores/`. +2. **Every edit to an upstream file gets a one-line entry below** — path, what, + why. No silent edits. +3. **Branches:** `main` tracks upstream releases (kept clean); `dev` is the VNC + integration + Vercel deploy branch; `vnc/*` are feature branches. +4. **Syncing upstream:** `git fetch upstream && git merge upstream/main` onto + `main`, then merge `main` into `dev`. Resolve using this log. + +## Divergences + +| Date | File / area | Change | Why | +|------|-------------|--------|-----| +| 2026-08-03 | `vnc/` (new) | Added VNC customization dir + this log | Fork bootstrap | +| 2026-08-03 | `VNCMAIL-SETUP.md` (new) | Vercel deploy runbook | Deploy on Vercel as project "VNCmail+" | + +_(append new rows as you diverge)_ diff --git a/vnc/branding/README.md b/vnc/branding/README.md new file mode 100644 index 00000000..0c0a6838 --- /dev/null +++ b/vnc/branding/README.md @@ -0,0 +1,19 @@ +# vnc/branding + +Drop VNCmail+ brand assets here (logos, favicon, PWA icons), then point the +runtime branding env vars at them. Most branding needs **no code edit** — it's +all env-driven and read at runtime. + +Suggested assets: +- `logo-light.svg` / `logo-dark.svg` → `APP_LOGO_LIGHT_URL` / `APP_LOGO_DARK_URL` +- `login-logo-light.svg` / `login-logo-dark.svg` → `LOGIN_LOGO_LIGHT_URL` / `LOGIN_LOGO_DARK_URL` +- `favicon.ico` → `FAVICON_URL` +- `pwa-icon.png` (512×512) → `PWA_ICON_URL` + +To serve these from the app itself, copy them into `public/branding/` and set the +URLs to `/branding/`. To serve from a CDN, set absolute URLs. + +Theme colors: `PWA_THEME_COLOR`, `PWA_BACKGROUND_COLOR`. + +See `VNCMAIL-SETUP.md` and upstream `.env.example` (branding section) for the full +list. diff --git a/vnc/overrides/README.md b/vnc/overrides/README.md new file mode 100644 index 00000000..59ad8676 --- /dev/null +++ b/vnc/overrides/README.md @@ -0,0 +1,15 @@ +# vnc/overrides + +Home for VNC-specific UI overrides that go beyond env-driven branding. + +Keep changes here (and imported into upstream files with a **single, logged** +edit) rather than editing upstream components in place — it keeps +`git merge upstream/main` cheap. + +Pattern: +- Put a replacement component / theme token / CSS layer in this folder. +- Wire it in with the smallest possible edit to the upstream file. +- Record that edit in `../VNC-CHANGES.md`. + +If you find yourself editing many upstream files for one feature, stop and +reconsider whether it can be an override or an upstream contribution instead. diff --git a/vnc/vercel.env.template b/vnc/vercel.env.template new file mode 100644 index 00000000..68db9b6c --- /dev/null +++ b/vnc/vercel.env.template @@ -0,0 +1,38 @@ +# ──────────────────────────────────────────────────────────────── +# VNCmail+ · Vercel environment variables +# Paste these into Vercel → Project "vncmail-plus" → Settings → +# Environment Variables. Do NOT commit real secret values. +# All vars are read at RUNTIME (no rebuild needed to change them), +# except NEXT_PUBLIC_BASE_PATH. +# ──────────────────────────────────────────────────────────────── + +# --- Core: connect to Stalwart over JMAP --- +# Setting this skips the setup wizard and uses env-managed config +# (important on Vercel, where the wizard's disk config is not persisted). +JMAP_SERVER_URL=https://stalwart.sandbox.vnc.de + +# --- Session encryption (mark as "Sensitive" in Vercel) --- +# Generate with: openssl rand -base64 32 +SESSION_SECRET=__PASTE_GENERATED_SECRET__ + +# --- Branding --- +APP_NAME=VNCmail+ +APP_SHORT_NAME=VNCmail+ +LOGIN_COMPANY_NAME=VNC + +# --- Quiet the periodic update check (avoids disk/network on serverless) --- +BULWARK_UPDATE_CHECK=off + +# ──────────────────────────────────────────────────────────────── +# Intentionally NOT set (defaults are correct for a Vercel deploy): +# OAUTH_ENABLED → unset = basic auth via Stalwart (chosen) +# SETTINGS_SYNC_ENABLED → unset = off (needs a persistent disk; skip on Vercel) +# BULWARK_TELEMETRY → unset = off (opt-in only) +# NEXT_PUBLIC_BASE_PATH → unset = deploy at domain root +# +# Add later if needed: +# OAUTH_ENABLED / OAUTH_ISSUER_URL / OAUTH_CLIENT_ID / OAUTH_CLIENT_SECRET +# → SSO via vncdirectory (follow-up, not first deploy) +# APP_LOGO_LIGHT_URL / LOGIN_LOGO_LIGHT_URL / FAVICON_URL / PWA_ICON_URL +# → VNC brand assets (see vnc/branding/) +# ────────────────────────────────────────────────────────────────