# 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.

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](https://planpa.ge/docs/self-host-install.md)). 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](https://planpa.ge/docs/github.md) 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](https://developers.cloudflare.com/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](https://developers.cloudflare.com/cloudflare-for-platforms/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](https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/start/advanced-settings/worker-as-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:

```sh
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](https://polar.sh): 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.
