# Install

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

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

```sh
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

```sh
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

```sh
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

```sh
pnpm selfhost:migrate
```

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

## 5. Deploy

```sh
pnpm selfhost:deploy
```

This reads the list of databases from the one you just migrated (there's only one until you [scale](https://planpa.ge/docs/self-host-scaling.md)), 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`:

```sh
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:

```sh
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:

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

[Connect an agent](https://planpa.ge/docs/connect-an-agent.md) covers every client. Wherever these docs say `app.planpa.ge`, use your app host.

## Next

- [Configure](https://planpa.ge/docs/self-host-configure.md) the optional parts: the GitHub App, push notifications, custom share domains and a front page.
- [Updating](https://planpa.ge/docs/self-host-update.md) explains how to take new versions.
