Public module integrations: see the catalog API contract.
Payload CMS V3 Website Template
One-click deploy on Railway!
Need help?
Step by step guide and instructions
A powerful, flexible, and production-ready Payload CMS V3 website builder with PostgreSQL database.
This repo powers the RaidGuild Portal: a CMS-backed surface for briefs, projects, threads, activity, sessions, profiles, recognition, contribution requests, modules, notifications, and contributor workflows.
Start with:
The Portal should make real community activity visible and help people find a useful next step. It should not become a project management system, Discord replacement, course platform, handbook dump, or generic AI content feed.
This project started from a Payload CMS website boilerplate and still uses
Payload, Next.js, and PostgreSQL as its foundation. Some lower sections of this
README retain setup notes from the original template, but product direction now
lives in docs/.
- Payload CMS:
3.82.1 - Next.js:
16.2.5 - Node.js:
>=22.23.4 <23
- Authentication: Robust user authentication system
- Access Control: Role-based access control for admins and users
- Premium Content: Gated content for authenticated users
- Comments: User commenting system with admin approval
- Layout Builder: Flexible content creation with pre-configured blocks
- Interactive Artifacts: Sandboxed Post embeds from approved artifact origins
- Draft Preview: Preview unpublished content before going live
- SEO: Built-in SEO optimization tools
- Redirects: Easy management of URL redirects
- PostgreSQL Support: Configured for both local and production use
The public Portal exposes /robots.txt, /sitemap.xml, and bounded CMS sitemap
shards. The robots handler lives at src/app/robots.txt/route.ts; the static
sitemap and CMS shard sources live under src/app/(frontend). Sitemap content uses
hourly revalidation so crawler traffic does not execute uncached CMS scans on
every request; robots.txt refreshes the lightweight shard manifest from
collection counts so newly required shards are advertised. To add a public
static route, update PUBLIC_STATIC_SITEMAP_PATHS in sitemap-config.ts. To add
a CMS-backed route type, extend sitemap-shards.ts with its publication/visibility
filters and canonical path builder. sitemaps/sitemap-data.ts collects eligible
documents, and sitemaps/sitemap/[id]/route.ts serves the XML with on-demand ISR. Keep each
shard below the configured entry limit and advertise it through robots.txt.
Never add a collection based only on the existence of a frontend route; member,
admin, draft, preview, account, API, search, and utility URLs must remain
excluded.
Use one-click deploy template:
Repository deployments use railway.json to keep image builds
database-independent. Railway runs corepack pnpm migrate:deploy as a
pre-deploy command, after the image builds and before traffic moves to the new
deployment. A failed migration stops the deployment.
For a branch preview against production data, create a second Portal service in
the production Railway environment, connect it to the preview branch, and give
it the same DATABASE_URI, PAYLOAD_SECRET, and service variables as the
production Portal. Give the preview its own public domain and set
NEXT_PUBLIC_SERVER_URL to that domain. Do not attach or reset a database, run
seed commands, or use the local reset scripts. Preview migrations must be
forward-compatible with the currently running production application.
Because the preview shares production state, its writes and migrations are
real. Rejecting the PR does not roll a migration back; remove obsolete schema
later with another reviewed forward migration. Only use additive or otherwise
backward-compatible migrations while production and preview code coexist.
If the preview does not mount the production media volume, set
MEDIA_FALLBACK_ORIGIN to the old Portal service's stable Railway HTTPS hostname.
Do not use portal.raidguild.org: after the DNS move, that domain will point at
the new service. Missing /media/* and /api/media/file/* reads then stream
from the old service. The Payload file endpoint still applies its media access
check and serves local uploads first. Treat that preview as read-only for media:
uploads written to its ephemeral filesystem will not survive deployment and are
not copied to the production Portal volume.
To make both Portal services use durable media, configure the existing shared
Railway S3 bucket for each service. Map that bucket's BUCKET, ENDPOINT,
REGION, ACCESS_KEY_ID, and SECRET_ACCESS_KEY variables to Portal's
MEDIA_S3_BUCKET, MEDIA_S3_ENDPOINT, MEDIA_S3_REGION,
MEDIA_S3_ACCESS_KEY_ID, and MEDIA_S3_SECRET_ACCESS_KEY. Set
MEDIA_STORAGE=s3 only after the old files are copied and checked. The adapter
stores all Portal objects under the fixed portal/media/ prefix; other apps'
keys in the bucket are outside that namespace. The Payload file route enforces
that namespace while normal media metadata remains publicly readable. The
default MEDIA_STORAGE=local keeps development and the old volume working.
MEDIA_S3_FORCE_PATH_STYLE=true is available for endpoints that require it.
For browser uploads to S3, allow the Portal admin origin in the bucket's CORS
configuration with the PUT method and Content-Type request header. Preserve
the bucket's other CORS rules because the bucket is shared. After CORS is in
place, set MEDIA_DIRECT_UPLOADS=true on that Portal service. The admin upload
form then sends file bytes to S3 using a short-lived signed URL and saves the
Media record through Payload. Failed authorization or S3 transfers display an
error in the admin form so the upload can be retried. Payload still reads the
uploaded object when it creates the Media record and image sizes.
For the volume-to-bucket cutover, deploy the additive media-prefix migration
and storage-capable code to both services with MEDIA_STORAGE=local. Set
MEDIA_UPLOADS_PAUSED=true on both services for the final copy window; this
blocks media create, update, and delete while other content and reads continue.
Export every media document (including all pages of /api/media?limit=100) as
{"docs":[...]} and make that JSON available on the old service. On that
service, run the tool against its mounted /app/public/media directory:
node scripts/migrateMediaToS3.mjs --manifest /tmp/portal-media-manifest.json --media-dir /app/public/media
node scripts/migrateMediaToS3.mjs --manifest /tmp/portal-media-manifest.json --media-dir /app/public/media --applyThe first command is a dry run. Review missing files, orphan files, and
collisions before applying. The copy includes each referenced original and
image size, keeps content types, skips byte-identical existing objects, and
never deletes or overwrites a different object. Re-run it after any interrupted
copy; the result should have no missing files, collisions, or pending copies.
The tool spaces PUT requests by 200 ms and retries Railway S3 SlowDown, 429,
and 503 responses with bounded backoff, reopening each file for a retry. It
reports progress every 50 files on stderr. If Railway continues throttling,
re-run after a short pause; completed objects are checked by content before
being skipped. --write-interval-ms 500 (or MEDIA_S3_WRITE_INTERVAL_MS=500)
slows writes further; accepted values are 100–5000 ms.
Then enable MEDIA_STORAGE=s3 on both services, verify several original and
resized image URLs and an upload, and clear MEDIA_UPLOADS_PAUSED. Keep the old
volume until the S3 deployment has been verified and any new S3 uploads are
accounted for in a rollback plan. A local-mode rollback after new S3 uploads
needs those new objects copied back to the volume first.
Post interactiveEmbed blocks accept only exact HTTPS origins listed in
INTERACTIVE_ARTIFACT_ORIGINS. Keep executable artifacts on a separate origin
from Portal; the frontend renders them in an iframe sandbox with scripts only.
- Clone the project or fork this repository.
- Copy
.env.exampleto.envand fill in your values. - Start PostgreSQL:
docker compose up -d postgres - Install dependencies:
corepack pnpm install - Apply migrations:
corepack pnpm payload migrate - Run development mode:
corepack pnpm dev
For a production-style local run after applying migrations:
corepack pnpm build
corepack pnpm startTo reset a non-Docker local PostgreSQL database, set DATABASE_URI to a local
host database in .env, then run:
corepack pnpm db:reset:local
corepack pnpm payload migrateThe reset script refuses non-local database hosts and prompts for confirmation
before dropping the database. Use corepack pnpm db:reset:local:migrate to
reset and immediately run migrations.
To seed local starter content for browser testing, run:
corepack pnpm db:seed:localThis upserts the portal starter content and ensures a local admin account exists:
- email:
local-admin@example.com - password:
password
It also creates a local-admin profile and two sessions hosted by that profile:
Local Artifact Upload Test - Past SessionLocal Host Planning Session - Future Session
Use corepack pnpm db:reset:local:seed for a fresh local reset, migration, and
seed in one command. The seed script also refuses non-local database hosts.
Pass -- --skip-admin to avoid creating the local admin account, or -- --full
to run the older destructive full demo seed.
Payload email delivery is optional in local development. Without SENDGRID_API_KEY, Payload writes email output to the server console.
Set these variables to enable SendGrid SMTP delivery for password resets, welcome emails, account email verification, and legacy profile claim verification:
SENDGRID_API_KEYEMAIL_FROM_ADDRESSEMAIL_FROM_NAME
The public reset flow is available at /forgot-password and /reset-password?token=....
Logged-in users can verify their account email from /me; self-serve signups start as unverified and become contributor after verification.
Legacy profile claims are requested from /me; matching unclaimed profiles send a verification link to the legacy claimEmail before the profile is attached to the logged-in user and the account is promoted to member.
The optional Newsletter module at /newsletter lets editors create or update
listmonk campaign drafts from Portal posts and send test emails. listmonk owns
subscriber lists, unsubscribes, archives, bounces, and final production sends.
Set these variables to enable the integration:
LISTMONK_URLLISTMONK_API_USERLISTMONK_API_TOKENLISTMONK_TEMPLATE_IDLISTMONK_DEFAULT_LIST_IDSLISTMONK_FROM_EMAILNEWSLETTER_DEFAULT_TEST_EMAIL
The frontend includes a small widget bubble that links to /feedback for
authenticated bug reports and product notes. It is enabled by default.
Set NEXT_PUBLIC_WIDGET_BUBBLE_ENABLED=false to hide the floating widget without
removing the feedback route or admin collection.
The Playwright suite boots a fresh PostgreSQL container, builds the app from scratch, creates the first admin user through the onboarding UI, upserts the portal starter content, submits a public comment, approves it in the admin UI, and verifies it appears on the public post page.
Before the first run, make sure Docker Desktop is running. The suite starts a fresh PostgreSQL container automatically.
The admin dashboard seed action is for local/dev setup. It is hidden and blocked on hosted Railway/Vercel environments unless ENABLE_ADMIN_SEED_ACTION=true is explicitly set. Locally, it is non-destructive: it upserts the portal starter records by stable slugs or titles and does not clear existing CMS content. It may update existing starter records with the same identifiers.
The older full reset seed remains in code for local reset workflows only; do not wire it to hosted production without an explicit database reset intent.
- Install everything required for e2e:
corepack pnpm e2e:install - Run the suite headlessly:
corepack pnpm test:e2e - Run the suite with a visible browser:
corepack pnpm test:e2e:headed - Run the suite slowly and keep the browser open for manual review:
corepack pnpm test:e2e:manual
What e2e:install does:
- Installs project dependencies
- Rebuilds native dependencies used by the app on Windows, including
sharpandesbuild - Downloads the Chromium browser used by Playwright
If you prefer npm, you can run:
npm run e2e:installnpm run test:e2enpm run test:e2e:headednpm run test:e2e:manual
test:e2e:manual runs the suite in headed mode with a visible slowdown between actions and pauses only at the end of the happy path. While paused, the browser stays open so you can click around and manually inspect seeded content, the admin area, and public pages. When you are done, resume or stop the Playwright session from the inspector/terminal.
- Database: PostgreSQL
- Node.js: Compatible version as specified in
package.json
E2E builds against an empty local PostgreSQL database before running migrations, matching Railway image build → pre-deploy migrations → application startup. Database-backed sitemap shards are generated on request and cached for one hour.