Quick Start

Three development modes depending on what you're testing.

Prerequisites

• Node.js 20+
• git clone the repo and cd SommelierArena

Mode A — Fast daily dev (recommended)

Best for feature work. No Docker needed.

# Terminal 1 — PartyKit backend (port 1999)
npx partykit dev

No Cloudflare account needed for local dev

npx partykit dev runs a local in-memory simulator — it emulates Cloudflare Durable Objects entirely on your machine with no internet connection required. Note: Cloudflare KV (HOSTS_KV) is not available locally; session history comes from browser localStorage only. See Configuration & Environments for the full comparison.

After any backend change — redeploy!

Whenever you modify files under back/ (game.ts, utils.ts, constants.ts, etc.), you must redeploy to Cloudflare for the changes to take effect in production:

npx partykit deploy   # from repo root
# or
cd back && npm run deploy

The proxy-worker does not need redeployment for backend-only changes.

# Terminal 2 — Astro frontend (port 4321)
cd front
cp .env.example .env.local # PUBLIC_PARTYKIT_HOST=localhost:1999
npm run dev

Open http://localhost:4321/host (host) and http://localhost:4321/play (participant).

Mode B — Full integration (Docker)

Best for E2E tests and nginx/proxy validation.

docker-compose up --build

Service	URL
Frontend (nginx)	http://localhost:4321
PartyKit backend	http://localhost:1999
Docs (Docusaurus)	http://localhost:3002

Why nginx?

In Mode B, the front container runs nginx instead of the Astro dev server. nginx is necessary because:

1. Astro builds to static files — npm run build produces plain HTML/JS/CSS; there's no Node.js server at request time, so something must serve them.
2. SPA routing — nginx's try_files $uri $uri/index.html /index.html ensures /host and /play return index.html without a 404.
3. Same-origin WebSocket proxy — nginx forwards /parties/* requests to the PartyKit backend container on port 1999, keeping browser–backend traffic on a single origin (no CORS).

absolute_redirect off in front/nginx.conf ensures nginx uses relative Location headers, which is safer for SPA routing in various proxy environments.

For daily development, you don't need nginx at all — Mode A uses Astro's built-in dev server on port 4321, which handles routing and WebSocket proxy natively via PUBLIC_PARTYKIT_HOST.

Alternative: Caddy provides equivalent functionality with a simpler config syntax. See Configuration & Environments for the full nginx walkthrough and Caddy comparison.

Docker cheat sheet

# Start the full stack
docker-compose up --build -d

# Stop the full stack
docker-compose down

# Rebuild a single service
docker-compose up --build -d front

# View logs
docker-compose logs -f

⚠️ Important: Use docker-compose down to stop the running stack. If you started the stack with additional flags or in a different context, ensure you stop the correct compose project instance.

Mode C — Docs only

cd docs-site
npm run start:local
# → http://localhost:3002

Docs site — local search & preview

Certificates / Playwright trust

If your network performs TLS interception (corporate proxy like Zscaler), Playwright's browser downloads may fail with TLS errors. Convert your organization's root certificate to PEM and use it for the single Playwright install command.

1. Convert DER (.cer / .crt) to PEM if needed:

openssl x509 -in "/path/to/org-root-ca.cer" -inform DER -out "/path/to/org-root-ca.pem" -outform PEM

2. Run the Playwright installer from the e2e directory while trusting the PEM file (one-off):

cd e2e
NODE_EXTRA_CA_CERTS="/path/to/org-root-ca.pem" npx playwright install --with-deps

Notes:

• Use a full filesystem path for NODE_EXTRA_CA_CERTS (do not check the PEM into source control).
• If you are behind an HTTP proxy, prefix the command with HTTPS_PROXY="http://proxy:port".
• Avoid NODE_TLS_REJECT_UNAUTHORIZED=0 in CI or shared environments — it disables TLS verification globally.

This project uses a local, file-based search plugin for Docusaurus to provide a search box in the docs navbar.

Quick start (dev):

1. Install dependencies:

   cd docs-site
   npm ci

2. Start the dev server (live reload):

   npm run start:local

3. Open http://localhost:3002 and use the search box in the navbar.

Preview built site (parity with production)

This repository standardizes on building the docs for deployment under /docs (Cloudflare Pages). To preview the site exactly as production will serve it:

# Build with DOCS_BASE_URL=/docs
cd docs-site
npm run build:local

# Serve the built site mounted at /docs
npm run serve:docs
# → http://localhost:3002/docs

If you prefer to preview the site at root (/), build with DOCS_BASE_URL=/ and use npm run serve to open http://localhost:3002/.

Notes

• The plugin dependency (@cmfcmf/docusaurus-search-local) is declared in package.json and will be installed by npm ci.
• The site configuration in docusaurus.config.ts will load the plugin if installed. If you build the docs inside Docker or CI, npm ci in the Dockerfile will ensure the plugin is available at build time.
• If npm ci fails in your environment, inspect the npm logs and ensure a network/proxy is configured correctly.
• See the Configuration & Environments page for env var details, nginx explanation, and storage layer breakdown.

Run tests

# Frontend unit tests (Vitest + RTL)
cd front && npm test

# E2E tests (requires Mode B Docker stack running)
cd e2e && npm test -- --project=chromium

Environment variables

Variable	Where	Value
PUBLIC_PARTYKIT_HOST	front/.env.local	localhost:1999 (local)
PUBLIC_PARTYKIT_HOST	Cloudflare Pages dashboard	sommelier-arena.USERNAME.partykit.dev (prod)

See front/.env.example for a template.

Note: Sessions persist in your browser's localStorage. Use the 🗑 button on the Host Dashboard to clean up old sessions.