Self-hosting

Install

Create the Cloudflare resources, fill in the config, set the secrets and deploy your own planpage, step by step.

For agents: this page as markdown · llms.txt

This takes about twenty minutes. You need a Cloudflare account on Workers Paid with a domain on it, and Node.js 22 or later, pnpm 10 and git on your computer. The examples use planpage.example.com for the app and share.planpage.example.com for share pages; use your own hosts.

1. Get the code

git clone https://github.com/Bifrostdotgg/planpage.git
cd planpage
pnpm install
cd apps/web
npx wrangler login

Every command from here on runs in apps/web.

2. Create the resources

npx wrangler d1 create planpage
npx wrangler kv namespace create OAUTH_KV
npx wrangler r2 bucket create planpage-images

The first two print an id. Keep them for the next step. If R2 says it isn't enabled, turn it on once under R2 in the Cloudflare dashboard and run the command again.

3. Fill in the config

cp wrangler.selfhost.example.jsonc wrangler.selfhost.jsonc

Open wrangler.selfhost.jsonc and change every line marked CHANGE:

Setting What to put
Worker name Any name, such as planpage.
Routes Your app host and your share host. Both must be on a zone in this Cloudflare account. Cloudflare creates the DNS records when you deploy.
BETTER_AUTH_URL https:// and your app host, with no trailing slash.
SHARE_HOST Your share host, without https://.
ADMIN_EMAILS Your email address, so you become admin (step 7). Separate several with commas.
D1 database id The id from wrangler d1 create.
KV id The id from wrangler kv namespace create.
R2 bucket name The bucket you created.

Leave wrangler.jsonc alone. It is planpa.ge's own config, and keeping your settings in a separate file means pulling updates never conflicts with them.

Two parts are optional. Browser (headless Chrome, called Browser Run in Cloudflare) renders diagrams to images for share pages and draws link preview cards; without it, diagrams still render in the app. Ratelimits slows down scrapers on share pages. Delete either block if you don't want it.

4. Create the database tables

pnpm selfhost:migrate

This applies every migration in packages/db/migrations to your D1 database. Answer yes when it asks.

5. Deploy

pnpm selfhost:deploy

This reads the list of databases from the one you just migrated (there's only one until you scale), builds the app against your config and deploys it. The first deploy also creates the custom domains, which can take a minute or two to get certificates.

6. Set the secrets

Two secrets are required. Generate each with openssl rand -base64 32:

npx wrangler secret put BETTER_AUTH_SECRET -c wrangler.selfhost.jsonc
npx wrangler secret put SETTINGS_KEY -c wrangler.selfhost.jsonc
  • BETTER_AUTH_SECRET signs sessions. Changing it signs everyone out.
  • SETTINGS_KEY encrypts the settings you save in Admin → System settings and the sign-in tokens planpage keeps. Keep a copy somewhere safe and never change it: anything encrypted with the old key becomes unreadable.

Then give people a way to sign in. You need at least one of these:

  • Email sign-in links: set SMTP_HOST, SMTP_PORT, SMTP_SECURITY, SMTP_USERNAME, SMTP_PASSWORD and SMTP_FROM_ADDRESS. Workers can't connect on port 25, so use 587 with starttls or 465 with tls.
  • GitHub: create an OAuth app with the callback URL https://planpage.example.com/api/auth/callback/github, then set GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET.
  • Discord: the same, with the callback ending in /discord, and DISCORD_CLIENT_ID and DISCORD_CLIENT_SECRET.

Set each one the same way:

npx wrangler secret put SMTP_HOST -c wrangler.selfhost.jsonc

Every secret takes effect straight away; you don't need to deploy again. apps/web/.dev.vars.example lists every setting with a short note.

7. Sign in and become admin

Open https://planpage.example.com and sign in with an address listed in ADMIN_EMAILS. The first person to sign in with a listed address, verified by the email link or by GitHub or Discord, becomes superadmin. Once a superadmin exists, the list does nothing, so nobody can use it to take over later. Until someone does, nobody runs the instance: set ADMIN_EMAILS before your first deploy and sign in straight after it, before you share the address.

You now have Admin in the rail. From there you can:

  • move the remaining settings into Admin → System settings, where you can change them without the command line;
  • send yourself a test email;
  • invite your team, or let them sign up and add them to a workspace.

8. Connect an agent

Point your agents at your own server instead of planpa.ge:

claude mcp add --transport http --scope user planpage https://planpage.example.com/mcp

Connect an agent covers every client. Wherever these docs say app.planpa.ge, use your app host.

Next

  • Configure the optional parts: the GitHub App, push notifications, custom share domains and a front page.
  • Updating explains how to take new versions.