Skip to Content
planning-poker

πŸ› οΈ Self-hosting

How rooms work under the hood, and how to run, deploy and load-test your own table.

planning-poker is two pieces: a Next.js app for the table, and a PartyServer room server on Cloudflare Workers that holds the truth.

How rooms work

Each room is a Durable Object (the PokerRoom class in party/index.ts, bound as Main in wrangler.jsonc). Every participant, host included, connects to it over a WebSocket at /parties/main/<code>. The server owns the room state, applies each message, and broadcasts the result to every connection; each vote is masked from everyone but its owner until the reveal.

  • Persistence. The room state and the host secret are saved to Durable Object storage on every change, so a room survives refreshes, reconnects and the server going to sleep.
  • Clean-up. Each connect and disconnect pushes a clean-up alarm 24 hours out. If nobody is connected when it fires, the room is wiped, host included; otherwise it waits another 24 hours.
  • Limits. Names and avatars are cut to 120 characters, ids and the host secret to 128, and a client can send at most one reaction every 250 ms.

What the browser keeps

Nothing is stored server-side about a person beyond the room they are in. The browser keeps the rest in localStorage:

KeyHolds
pp-settingsYour name and avatar
pp-preferred-deckThe deck to start new rooms with
poker-client-<code>Your player id in that room
poker-host-<code>The host secret, if you created that room
poker-seen-<code>When you last visited that room

Per-room keys are pruned after seven days without a visit.

Running it locally

npm install
npm run party:dev   # room server on ws://127.0.0.1:8787
npm run dev         # the app on http://localhost:3000

Scripts

ScriptWhat it does
npm run devStart the Next.js dev server
npm run party:devStart the room server locally (wrangler dev)
npm run party:deployDeploy the room server to Cloudflare Workers (wrangler deploy)
npm run buildProduction build of the app
npm run startServe the production build
npm run crew -- CODEFill a room with fake voters (see below)
npm run lintRun ESLint
npm testRun the unit tests (Vitest)

Pointing the app at your room server

The app reads one setting at build time:

VariableDefault
NEXT_PUBLIC_PARTYKIT_HOST127.0.0.1:8787 in development, planning-poker.kud-space.workers.dev in production builds

To run your own table end to end, deploy the room server with npm run party:deploy, then build the app with NEXT_PUBLIC_PARTYKIT_HOST set to your worker's host name (no scheme).

Testing with a crew

scripts/crew.js drops a crew of fake players into a room so you can try a full table on your own:

npm run crew -- PKD8QC              # seven players on the local room server
npm run crew -- PKD8QC --count 3    # three players
npm run crew -- PKD8QC --prod       # against the deployed room server

The crew vote a random value from 1, 2, 3, 5, 8 and 13 a few seconds after joining, and vote again after every new round. With --prod they connect over wss:// to NEXT_PUBLIC_PARTYKIT_HOST, falling back to the default production host. They leave after 15 minutes, or on Ctrl-C. The crew has at most eight members.