diff --git a/apps/events/CHANGELOG.md b/apps/events/CHANGELOG.md index 7ff8f07..eec26fc 100644 --- a/apps/events/CHANGELOG.md +++ b/apps/events/CHANGELOG.md @@ -7,6 +7,17 @@ and this project follows [Semantic Versioning](https://semver.org/). ## [Unreleased] +### Changed + +- **Everything the backend serves is under `/api`** (for 2.3.0), so the site and its API can share + one address (`events.church.co.za`, no `events-api.` record) with a single proxy rule: `/api` → + backend port, everything else → frontend port (DEPLOYMENT.md, "One address, one rule"). The + status page is at `/api` (`/` redirects there), health at `/api/health`, the API reference at + `/api/docs/v2` and uploaded files at `/api/uploads/…`. Stored paths stay `/uploads/…`; pictures, + logos and attachments are given out as `/api/uploads/…`, and so are WhatsApp ticket PDFs. +- The old paths keep working on the backend: `/health` and `/uploads/…` answer as before, and + `/docs` and `/docs/v2` redirect to `/api/docs/v2`. A missing file under `/api/uploads` is 404. + ## [2.1.1] - 2026-11-03 ### Fixed diff --git a/apps/events/DEPLOYMENT.md b/apps/events/DEPLOYMENT.md index 87e5fc4..b6379cd 100644 --- a/apps/events/DEPLOYMENT.md +++ b/apps/events/DEPLOYMENT.md @@ -38,6 +38,27 @@ visitor ──http───▶ frps (vhost_http_port) ══tunnel══▶ frp On this server, nginx sends `/api`, `/uploads`, `/health` and `/docs` to the backend (port 5000) and everything else to the Next.js site (port 3000), the same as a normal install. +### One address, one rule (2.3.0 and later) + +From 2.3.0 everything the backend serves is under **`/api`**: the API (`/api/v2`), the status page +(`/api`), health (`/api/health`), the API reference (`/api/docs/v2`) and uploaded files +(`/api/uploads/…`). So the site and its API share one address (`events.yourchurch.org`, no +separate `events-api.` record), and a web server or panel such as FastPanel needs a single +rule: + +| Path | Goes to | +|------|---------| +| `/api` and everything under it | the backend, `http://127.0.0.1:5000` | +| everything else | the frontend, `http://127.0.0.1:3000` | + +Set `BACKEND_URL` (backend `.env`) and `NEXT_PUBLIC_API_URL` (frontend `.env.production`) to the +same `https://` address as `FRONTEND_URL`, then rebuild the frontend. The old paths (`/health`, +`/docs/v2`, `/uploads/…`) still answer on the backend's port, so a site with a separate API +address keeps working unchanged. With only `/api` routed, links made before 2.3.0 that point at +`https:///uploads/…` stop working (they aren't stored that way, but could be in an old +email); keep the four-path rule above if that matters. Pictures, logos and attachments are all +given out as `/api/uploads/…` from 2.3.0. + ## 2. Before you start - Ubuntu 22.04 or 24.04 on this server, with `frpc` already installed and connected (it runs as @@ -264,7 +285,7 @@ setup). If the `[hope-events-https]` section fails to start, check `journalctl - ## 6. Finish in the browser -1. Open `https://events.yourchurch.org/health` — it should answer with the version. +1. Open `https://events.yourchurch.org/api/health` (`/health` before 2.3.0) — it should answer with the version. 2. Open `https://events.yourchurch.org/setup`: create the admin account. 3. **Site settings → Licence**: enter the licence key to connect to the Hub. The site checks in every 15 minutes from then on (outgoing HTTPS to `events-hub.crosscode.co.za`, which frp diff --git a/apps/events/README.md b/apps/events/README.md index 727d69c..5a8e2ea 100644 --- a/apps/events/README.md +++ b/apps/events/README.md @@ -20,7 +20,7 @@ The backend provides a RESTful API for managing users, events, registrations, pa - Static uploads for event images Documentation: see Backend API Documentation and Backend README for environment setup and endpoints. -- API reference: `/docs/v2` on the running backend (OpenAPI; admin token) — ./backend/API_DOCUMENTATION.md +- API reference: `/api/docs/v2` on the running site (OpenAPI; admin token; `/docs/v2` before 2.3.0) — ./backend/API_DOCUMENTATION.md - Moving to 2.0 (v1 API removed): ./MIGRATING-TO-2.md - Backend README: ./backend/README.md @@ -156,7 +156,7 @@ set names that match your PM2 apps (`pm2 ls`) and the port you use. ## Useful Links -- API reference: `/docs/v2` on the running backend (OpenAPI; admin token) — ./backend/API_DOCUMENTATION.md +- API reference: `/api/docs/v2` on the running site (OpenAPI; admin token; `/docs/v2` before 2.3.0) — ./backend/API_DOCUMENTATION.md - Moving to 2.0 (v1 API removed): ./MIGRATING-TO-2.md - Backend README: ./backend/README.md - Frontend README: ./frontend/README.md diff --git a/apps/events/backend/src/app.js b/apps/events/backend/src/app.js index f021ea4..8db6b5b 100644 --- a/apps/events/backend/src/app.js +++ b/apps/events/backend/src/app.js @@ -153,8 +153,12 @@ app.use((req, res, next) => { // Licence suspended, revoked or missing: no new or edited events, registrations or payments (src/hub/readOnly.js). app.use(require('./hub/readOnly').licenceReadOnly); +// Everything the backend serves is under /api (2.3.0), so the site and its API can share one +// address: the web server sends /api to the backend and everything else to the frontend. The old +// paths (/, /health, /docs/v2, /uploads) still work for sites with a separate API address. + // Health for monitoring (and the Hub): no secrets, no personal information. -app.get('/health', async (req, res) => { +app.get(['/api/health', '/health'], async (req, res) => { const report = require('./hub/report'); let db = true; try { await prisma.$queryRaw`SELECT 1`; } catch { db = false; } @@ -174,11 +178,11 @@ app.use('/api/v2', linksRouter); app.use('/api/v2', require('./v2').v2Router()); // Links in messages already sent: v1 addresses answer 308 with their v2 one. app.use(legacyLinkRedirects); -app.use('/docs/v2', require('./v2').v2DocsRouter()); -// v1 (/api/…) was removed in 2.0. Still answered: provider webhooks (above, and WAWP's old -// address) and links in messages already sent (308s above, a mail app's one-click POST here). -app.use('/api', legacyV1Router); -app.use('/api', v1Removed); +app.use('/api/docs/v2', require('./v2').v2DocsRouter()); +app.get('/api/docs', (req, res) => res.redirect(301, '/api/docs/v2')); +// Before 2.3.0 the reference was at /docs/v2 (bookmarks, the old status page). +app.use('/docs/v2', (req, res) => res.redirect(301, `/api${req.originalUrl}`)); +app.get('/docs', (req, res) => res.redirect(301, '/api/docs/v2')); // Pre-warm the settings cache so synchronous helpers have DB values from startup const { getSettingSync, warmCache } = require('./utils/settingsCache'); @@ -187,12 +191,16 @@ warmCache().catch(() => {}); // handlers. Serving them inline lets a compromised/malicious upload run script // in the site's origin if opened directly, so pin the safe response headers // (no inline execution, no MIME-sniffing to HTML/script) on every asset here. -app.use('/uploads', express.static('public/uploads', { +// Stored paths stay "/uploads/…"; they're given out as /api/uploads/… (v2/schemas.ts absoluteUrl). +// /uploads still answers for links made before 2.3.0. +const uploads = express.static('public/uploads', { setHeaders: (res) => { res.setHeader('Content-Security-Policy', "default-src 'none'; style-src 'unsafe-inline'; sandbox"); res.setHeader('X-Content-Type-Options', 'nosniff'); }, -})); +}); +app.use('/api/uploads', uploads, notFound); // a missing file is 404, not "API v1 removed" +app.use('/uploads', uploads); // ── Shared page helpers ──────────────────────────────────────────────────────── @@ -268,8 +276,9 @@ app.get('/favicon.ico', (req, res) => { res.sendFile(path.join(__dirname, '..', 'src', 'favicon.ico')); }); -// ── Root route — status page ──────────────────────────────────────────────── -app.get('/', async (req, res) => { +// ── Status page, at /api (2.3.0); / sends you there ───────────────────────── +app.get('/', (req, res) => res.redirect(302, '/api')); +app.get('/api', async (req, res) => { const mem = process.memoryUsage(); const uptimeSec = process.uptime(); const now = new Date().toISOString(); @@ -335,15 +344,18 @@ app.get('/', async (req, res) => {
- API documentation (OpenAPI) is at /docs/v2 — it needs an admin account token. + API documentation (OpenAPI) is at /api/docs/v2 — it needs an admin account token.
`); res.send(html); }); -// /docs: the v1 reference went with v1 in 2.0; the API is documented at /docs/v2 (OpenAPI). -app.get('/docs', (req, res) => res.redirect(301, '/docs/v2')); +// v1 (/api/…) was removed in 2.0. Still answered: provider webhooks (above, and WAWP's old +// address) and links in messages already sent (308s above, a mail app's one-click POST here). +// Mounted after everything else under /api, since v1Removed answers 410 for any other /api path. +app.use('/api', legacyV1Router); +app.use('/api', v1Removed); // Error middleware app.use(notFound); diff --git a/apps/events/backend/src/controllers/eventController.js b/apps/events/backend/src/controllers/eventController.js index 4561204..1f27b4b 100644 --- a/apps/events/backend/src/controllers/eventController.js +++ b/apps/events/backend/src/controllers/eventController.js @@ -45,9 +45,10 @@ function toAbsoluteUrl(req, url) { } return raw; // keep as-is if already absolute and not localhost } - // Relative path like /uploads/... => prefix with request origin + // Relative path like /uploads/... => prefix with request origin; uploads are served under + // /api/uploads (2.3.0) so they reach the backend when the site and API share one address if (raw.startsWith('/')) { - return `${req.protocol}://${req.get('host')}${raw}`; + return `${req.protocol}://${req.get('host')}${raw.startsWith('/uploads/') ? `/api${raw}` : raw}`; } // Any other case, return as-is return raw; diff --git a/apps/events/backend/src/utils/whatsapp.js b/apps/events/backend/src/utils/whatsapp.js index d81fc6a..31a5d0c 100644 --- a/apps/events/backend/src/utils/whatsapp.js +++ b/apps/events/backend/src/utils/whatsapp.js @@ -269,7 +269,7 @@ async function sendPdf(toPhone, localPdfPath, filename, caption) { `Set BACKEND_URL to your public backend URL (e.g. https://api.yourdomain.com) in your .env file.` ); } - const pdfUrl = `${backendUrl}/uploads/tickets-temp/${tempName}`; + const pdfUrl = `${backendUrl}/api/uploads/tickets-temp/${tempName}`; const { token, instanceId } = await getConfig(); try { diff --git a/apps/events/backend/src/v2/index.ts b/apps/events/backend/src/v2/index.ts index 723cac9..e50bcfc 100644 --- a/apps/events/backend/src/v2/index.ts +++ b/apps/events/backend/src/v2/index.ts @@ -43,7 +43,7 @@ export function v2Router(): Router { } /** - * /docs/v2: Swagger UI (served from swagger-ui-dist, nothing from a CDN). The page itself is + * /api/docs/v2 (2.3.0; /docs/v2 before, which now redirects): Swagger UI (served from swagger-ui-dist, nothing from a CDN). The page itself is * public; it asks for an admin token and uses it to load openapi.json and to try requests. */ export function v2DocsRouter(): Router { @@ -62,7 +62,7 @@ const DOCS_HTML = ` Cross Events API v2 - +