Getting Started

This guide walks through running the monorepo locally, starting any single app, and running tests. If you only need the docs site, the quickstart for weiqui-docs section is enough.

Prerequisites

Tool	Version	Notes
Node.js	>=18 (CI uses 22)	Required for every app. Use a version manager (fnm, nvm).
pnpm	9.15.0	Pinned via Corepack. corepack enable && corepack prepare pnpm@9.15.0 --activate.
Docker	any recent	Used by weiqi-server, auth-app, and billing-indexer for Postgres / Redis / MinIO.
KataGo	binary in $PATH	Needed only when running katago-service against a real engine (the default adapter shells out).
Git	any recent	Monorepo uses sub-path package managers.

Install

git clone <repo-url> sharp.go
cd sharp.go
corepack enable
corepack prepare pnpm@9.15.0 --activate
pnpm install

pnpm install reads pnpm.overrides from the root package.json to pin critical transitive deps (next 16.2.4, hono ^4.11.7, esbuild ^0.25.12, lodash ^4.17.23, @modelcontextprotocol/sdk 1.24.3, mcp-handler 1.0.5).

Environment variables

Every deployable app ships an .env.example. Copy the ones you need:

cp apps/weiqi-server/.env.example     apps/weiqi-server/.env
cp apps/auth-app/.env.example         apps/auth-app/.env.local
cp apps/billing-indexer/.env.example  apps/billing-indexer/.env.billing-indexer
cp apps/katago-service/.env.example   apps/katago-service/.env
cp apps/main-app-astro/.env.example   apps/main-app-astro/.env
cp apps/game-web/.env.example         apps/game-web/.env
cp apps/mcp-bridge/.env.example       apps/mcp-bridge/.env

See Environment Variables for what each key does.

Start the dependency stack

weiqi-server and billing-indexer each ship their own docker-compose.yml (Postgres + Redis + MinIO + seed jobs). From the relevant app directory:

# weiqi-server dependencies (Postgres 54320, Redis 6379, MinIO 9000)
cd apps/weiqi-server
docker compose up -d

# auth-app dependencies (Postgres 5433, MinIO 9000)
cd apps/auth-app
docker compose --profile setup run --rm setup
docker compose up -d

# recognition-service is optional; only needed when working on board photo scan
cd apps/weiqi-server
docker compose --profile recognition up -d

Run everything

# Fan out dev mode across every app that defines a `dev` script (Turbo).
pnpm dev

This is convenient for a top-level overview but slow on cold start. Prefer running the apps you actually need.

Run a single app

pnpm --dir apps/<name> dev

App	Port	Command
weiqi-docs	4321	pnpm --dir apps/weiqi-docs dev
main-app-astro	3001	pnpm --dir apps/main-app-astro dev
weiqi-server	3002	pnpm --dir apps/weiqi-server dev
mcp-bridge	3003	pnpm --dir apps/mcp-bridge dev
auth-app	3004	pnpm --dir apps/auth-app dev
game-web	3001+	pnpm --dir apps/game-web dev
katago-service	4011	pnpm --dir apps/katago-service dev
recognition-service	4010	pnpm --dir apps/recognition-service dev
billing-indexer	9090	pnpm --dir apps/billing-indexer dev

game-web and main-app-astro both default to Vite’s port 3001; run only one at a time or override vite --port.

Run only the docs site

pnpm --dir apps/weiqi-docs dev
# open http://localhost:4321/

The docs site is fully static — no Docker, no env files, no database. Pagefind search index is regenerated on each astro build.

Tests

There is no root turbo test task. Run tests per package:

pnpm --dir packages/weiqi-engine test   # vitest (watch mode)
pnpm --dir packages/glicko test         # vitest
pnpm --dir apps/game-web test           # vitest run (one-shot)
pnpm --dir apps/weiqi-server test       # jest

Vitest configs are at apps/<name>/vitest.config.ts and packages/<name>/vite.config.ts. The engine package mirrors src/ under tests/ (e.g. packages/weiqi-engine/tests/engine/rules/base/canPlaceStone.test.ts).

Lint, format, typecheck

pnpm lint          # turbo fan-out
pnpm format        # prettier write (defaults: 3.8.1)
pnpm --dir apps/weiqi-server typecheck   # tsc --noEmit

ESLint flat config extends from packages/eslint-config (exports ./base, ./next, ./react-internal). TypeScript config extends from packages/typescript-config (exports base.json, vite.json, nextjs.json, react-library.json).

Clean

pnpm clean
# rimraf node_modules .turbo packages/*/node_modules apps/*/node_modules

Next steps

• Read Architecture to see how the services fit together.
• If you’re touching rules code, start with weiqi-engine.
• If you’re touching the bot ladder, see Bot Ladder.
• For deployment, see Deploy.