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/githubor/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:
- Turn on Cloudflare for SaaS for that zone and set your share host as its fallback origin.
- Route custom hostname traffic to your Worker. Cloudflare's guide Workers as your fallback origin covers both steps.
- 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.