Quick Start

Three development modes depending on what you're testing.

Prerequisites

• Node.js ≥22.12
• 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 disabled in all environments (binding removed — see Data Persistence); session history comes from browser localStorage only.

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), http://localhost:4321/play (participant), and http://localhost:4321/admin (admin dashboard).

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
Wine Answers Worker	http://localhost:1998
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.

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

WebSocket traffic is direct — nginx does not proxy WebSocket connections. The browser connects directly to ws://localhost:1999/parties/main/{code} (the back container is exposed on host port 1999). This keeps the nginx config simple with no /parties/ location block.

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 natively via PUBLIC_PARTYKIT_HOST.

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

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.
• If you build inside Docker or CI, npm ci in the Dockerfile ensures the plugin is available.
• See the Configuration & Environments page for env var details and storage layer breakdown.

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.

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)
PUBLIC_WINE_ANSWERS_URL	front/.env.local	http://localhost:1998 (local)
PUBLIC_WINE_ANSWERS_URL	Cloudflare Pages dashboard	https://<wine-answers-worker>.workers.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.