Self-hosting

Configure

Settings for a self-hosted planpage. Sign-in, email, the GitHub App, push notifications, custom share domains, a front page, data retention and billing.

For agents: this page as markdown · llms.txt

Most settings live in two places. Admin → System settings is easiest: it saves values encrypted in your database, and they win over Worker secrets of the same name. Worker secrets (npx wrangler secret put NAME -c wrangler.selfhost.jsonc) are for the few values planpage needs before anyone can sign in. The plain settings in the vars block of wrangler.selfhost.jsonc take effect on your next deploy.

Setting Where Needed
BETTER_AUTH_SECRET, SETTINGS_KEY Worker secret Always
BETTER_AUTH_URL, SHARE_HOST, ADMIN_EMAILS vars Always
Email (SMTP) Secret, then System settings For email sign-in, invitations and notification emails
Login providers (GitHub, Discord) Secret, then System settings For signing in with GitHub or Discord
GitHub App System settings For pull request links and status checks
Web push System settings For browser notifications
Custom domains System settings For share pages on your users' own domains
Data retention System settings Off by default
Databases System settings Not with one database
MARKETING_HOST vars For a front page on its own host
Billing vars and System settings Off by default

Sign-in

People can sign in with an email link, GitHub, Discord or a passkey they've added. Email and the two providers each turn on once their settings are filled in.

  • Email needs an SMTP server. Workers can't connect on port 25, so use 587 with STARTTLS or 465 with TLS. Admin → Emails sends a test message and shows what was sent.
  • GitHub and Discord need an OAuth app each, with the callback URL https://your-app-host/api/auth/callback/github or /discord.

Anyone who can reach your app host can create an account, and new accounts start with only a personal workspace. They see nothing else until someone invites them to a workspace.

Admins and staff

The first admin comes from ADMIN_EMAILS (see Install). After that, add more people in Admin → Staff and give each a role. Remove your address from ADMIN_EMAILS once you're set up if you like; it is only ever read while no superadmin exists.

Staff security in System settings can require passkeys for staff and sets how long a staff sign-in lasts.

GitHub App

The GitHub App links pull requests to plans, posts a comment on each pull request with its plan, and adds a planpage/approved status check that goes green when the plan is approved. Create a GitHub App with:

  • Setup URL: https://your-app-host/integrations/github/setup
  • Webhook URL: https://your-app-host/webhooks/github, with a webhook secret
  • Repository permissions: Metadata (read), Pull requests (read and write), Commit statuses (read and write)
  • Organization permission: Members (read)
  • Events: Pull request

Then paste its App ID, slug, private key and webhook secret into Admin → System settings → GitHub App. GitHub explains what people see once it's installed.

Push notifications

Open Admin → System settings → Web push and generate a key pair. People then turn on browser notifications in Your account → Notifications. Generating new keys later stops existing subscriptions, and people have to turn push back on.

Diagrams and preview cards

With the browser binding in your config, planpage renders Mermaid diagrams to images for share pages and draws link preview cards. Without it, diagrams render in the app as usual and share pages show their code. Cloudflare includes some browser time with Workers Paid and bills beyond that; see Browser Run pricing.

Custom share domains

Workspace owners can serve their share links from their own domain, such as plans.their-company.com. This uses Cloudflare for SaaS on the zone your share host is in:

  1. Turn on Cloudflare for SaaS for that zone and set your share host as its fallback origin.
  2. Route custom hostname traffic to your Worker. Cloudflare's guide Workers as your fallback origin covers both steps.
  3. Create an API token with SSL and Certificates: Edit on that zone, and put it and the zone id in Admin → System settings → Custom domains.

Workspace owners then add their domain in Workspace settings → General and create the CNAME record it shows them.

A front page

Leave MARKETING_HOST empty and your app host serves the app, these docs at /docs and the sign-in page at its root. To show the planpage front page on a separate host instead, add that host to routes and set MARKETING_HOST to it. The front page serves the docs too.

Data retention

A daily job deletes rows past their retention periods, such as expired sessions, the email log after 90 days and closed invitations. It only counts them until you turn on Admin → System settings → Data retention. Data retention lists every rule and what the last run counted. Export your database before you turn it on for the first time:

npx wrangler d1 export planpage --remote --output planpage-backup.sql -c wrangler.selfhost.jsonc

Databases

A self-hosted planpage keeps everything in one D1 database, and Admin → System settings → Databases has no effect then. Its close size only applies when more than one content database is bound: a database that reaches it takes no new documents, and its owners' next documents go to a fresh one.

Leave Add databases automatically off. It creates D1 databases through the Cloudflare API and relies on planpa.ge's deploy scripts to bind them, which selfhost:deploy doesn't run, so databases it made would never be used.

Billing

With BILLING_ENABLED set to "false", every workspace gets every feature and there is nothing to pay. You only need billing if you want to charge your own users. It works through Polar: set BILLING_ENABLED to "true", fill in Admin → System settings → Billing, point Polar's webhook at https://your-app-host/webhooks/polar, and map your plans to Polar products in Admin → Billing → Products.

Terms and privacy pages

/terms and /privacy are planpa.ge's own terms and privacy policy, written for Bifrost Development Ltd. They don't describe your deployment. If people outside your organization use it, replace apps/web/app/routes/terms.tsx and privacy.tsx with your own.