Pages CMS

Pages CMS is an open source CMS for GitHub repositories. It is especially well suited for static sites and content-driven apps built with tools like Jekyll, Hugo, Next.js, Astro, VuePress, and similar stacks.

You can use the hosted version directly at app.pagescms.org, or run your own local development copy from this repository.

Watch the demo ▶

Documentation

Full documentation lives at pagescms.org/docs.

Useful starting points:

• Install locally
• Create the GitHub App
• Environment variables
• Upgrading to 2.x

Use online

The easiest way to get started is the hosted version at app.pagescms.org.

Use that if you want to:

• try Pages CMS immediately,
• edit content without running anything locally,
• stay on the latest hosted version.

Local development

What you need

• PostgreSQL
• a GitHub App
• a local .env.local
• the Pages CMS repo checked out locally

Quick start

1. Clone the repository:

git clone https://github.com/pagescms/pagescms.git
cd pagescms

2. Start PostgreSQL locally:

docker run --name pagescms-db -e POSTGRES_USER=pagescms -e POSTGRES_PASSWORD=pagescms -e POSTGRES_DB=pagescms -p 5432:5432 -d postgres:16

3. Install dependencies:

npm install

4. Create .env.local with at least:

DATABASE_URL=postgresql://pagescms:pagescms@localhost:5432/pagescms
BETTER_AUTH_SECRET=your-random-secret
CRYPTO_KEY=your-random-secret

Optional but useful:

BASE_URL=https://cms.example.com
ADMIN_EMAILS=admin@example.com

Notes:

• In production, BASE_URL should be the single canonical URL for the app.
• Do not mix a custom domain and a *.netlify.app URL for the same install.
• ADMIN_EMAILS is a comma-separated allowlist for access to the admin panel.

Generate secrets with:

openssl rand -base64 32

5. Create your GitHub App with the helper:

npm run setup:github-app -- --base-url http://localhost:3000

Useful options:

• --owner-type personal|org
• --org <slug>
• --app-name "Pages CMS (local)"
• --env .env.local
• --no-open

6. Run database migrations:

npm run db:migrate

If cache state is known stale or corrupted, clear it with:

npm run db:clear-cache

7. Start the app:

npm run dev

If you need GitHub webhooks to reach your local app, use a public tunnel URL as the helper --base-url.

For more detail, see:

• Install locally
• Create the GitHub App
• Environment variables
• Caching

Support the project

• Contribute code
• Report issues
• Sponsor me
• Star the project on GitHub
• Join the Discord chat

License

Everything in this repo is released under the MIT License.