Cloudflare Pages Deployment

Overview

NuSaaS supports a split deployment model where the public frontend and documentation are hosted on Cloudflare Pages, while the Laravel API, Reverb, workers, and data services remain on the VPS.

Use this model when you want:

• faster global delivery for static assets
• simpler public routing for the marketing site and docs
• the backend to remain on your existing server infrastructure

Public topology

In this setup, the public origins are:

Surface	Public URL	Hosted on
Frontend	https://nusaas.com	Cloudflare Pages
Docs	https://docs.nusaas.com	Cloudflare Pages
API	https://api.nusaas.com	VPS
WebSocket	wss://ws.nusaas.com	VPS

Only the API and WebSocket services need public VPS exposure once the Pages domains are live.

Repository paths

NuSaaS is a monorepo. Use these repo subdirectories when configuring Cloudflare Pages:

Site	Root directory	Build command	Output directory
Frontend	web	npm run build	dist
Docs	docs-site	npm run build	build

Environment files

For the managed NuSaaS cloud deployment:

• backend env source: .env.cloud
• frontend env source: web/.env.cloud

At deploy time, these are copied to the active runtime files:

cp .env.cloud .env
cp web/.env.cloud web/.env.frontend

Do not use web/.env.frontend.example for the managed cloud deployment. That file is intended for self-hosters to fill with their own values.

Frontend Pages project

Recommended Cloudflare Pages settings for the public frontend:

• Production branch: main
• Root directory: web
• Build command: npm run build
• Build output directory: dist

Required frontend runtime values in web/.env.frontend include:

VITE_API_URL=https://api.nusaas.com
VITE_API_BASE_URL=https://api.nusaas.com
VITE_DOCS_URL=https://docs.nusaas.com
VITE_REVERB_HOST=ws.nusaas.com
VITE_REVERB_PORT=443
VITE_REVERB_SCHEME=wss

Docs Pages project

Recommended Cloudflare Pages settings for the documentation site:

• Production branch: main
• Root directory: docs-site
• Build command: npm run build
• Build output directory: build

If you deploy manually from a local machine instead of using Git integration:

cd docs-site
npm run build
npx wrangler pages deploy ./build --project-name nusaas-docs

VPS responsibilities

When using Cloudflare Pages for the public frontend and docs, the VPS should continue to serve:

• Laravel API
• Reverb / WebSocket traffic
• queue workers
• scheduler
• database
• Redis
• Meilisearch

You can keep using Cloudflare Tunnel or a reverse proxy for the backend side.

Cutover checklist

1. Deploy the frontend and docs Pages projects successfully.
2. Attach nusaas.com to the frontend Pages project.
3. Attach docs.nusaas.com to the docs Pages project.
4. Verify that api.nusaas.com still serves the backend correctly.
5. Verify that ws.nusaas.com still upgrades WebSocket connections correctly.
6. Confirm the frontend can call the API and open realtime channels.
7. Remove the old public web and docs tunnel/port exposure only after the custom domains are live and verified.

Verification

After cutover, verify:

• https://nusaas.com loads the frontend
• https://docs.nusaas.com loads the docs site
• docs footer "Main Site" links to https://nusaas.com
• frontend links to docs correctly
• browser API calls go to https://api.nusaas.com
• realtime connections use wss://ws.nusaas.com