敏捷项目管理

Run with Docker

docker compose up --build

Open http://localhost:8080.

Frontend build note

The Docker image and go run embed prebuilt assets under internal/httpapi/web/dist. If they are missing, build them:

cd internal/httpapi/web
npm install
npm run build

Then run docker compose up --build or go run ./cmd/scrumboy again from the repository root.

Quick Start

Runs in seconds. No setup required.

No .env file, TLS certificates, or encryption key are required to start the app.

Optional Configuration

Environment variables

• The app does not automatically load .env files.
• On Linux/macOS, export variables manually (for example: export SCRUMBOY_ENCRYPTION_KEY=...).
• On Windows, win_run_full.bat and win_run_anonymous.bat manage data/scrumboy.env automatically for local convenience.
• Precedence on Windows is: existing process env var SCRUMBOY_ENCRYPTION_KEY, then data/scrumboy.env, then legacy root scrumboy.env.
• The canonical Windows-managed local file format is SCRUMBOY_ENCRYPTION_KEY=<base64-32-byte-key>.
• Windows helper scripts still accept legacy raw single-line key files for backward compatibility.

OIDC / SSO login (optional)

Scrumboy supports OpenID Connect for single sign-on with any standards-compliant provider (Keycloak, Authentik, Auth0, Entra ID, etc.). OIDC is enabled by setting all four required environment variables:

Optional:

Local password authentication remains available by default alongside OIDC. After successful OIDC login, the user receives a standard Scrumboy session cookie. The IdP must return a verified email (email_verified: true). HTTPS is recommended when using OIDC to ensure session cookies are Secure.

See docs/oidc.md for full setup details, constraints, and troubleshooting.

TLS / HTTPS (optional)

• TLS is optional.
• HTTPS is enabled only when both SCRUMBOY_TLS_CERT and SCRUMBOY_TLS_KEY files exist.
• Otherwise, the server runs on HTTP by default.

PWA / Web Push (optional)

Install the app from the browser for a standalone window and better mobile UX. Background assignment alerts use the Web Push API with VAPID keys on the server. When both keys are set, signed-in clients attempt to subscribe automatically (browser permission may be prompted). Details and subscriber contact semantics: docs/pwa.md.

Config

Env vars and defaults are defined in internal/config/config.go. ResolveDataDir uses DATA_DIR and SQLITE_PATH as documented there. None of these are required for basic startup.

docker-compose.yml overrides some of these (e.g. SQLITE_BUSY_TIMEOUT_MS=5000).

---

Integrations & API Access

Scrumboy supports API access tokens for automation, integrations, and programmatic MCP access (legacy HTTP and JSON-RPC - see below). Full MCP guide for developers and agents: docs/mcp.md.

You can create a token from the API and use it to call MCP endpoints directly - no browser session or cookies required.

Create a token (requires login session):

curl -b cookies.txt -X POST http://localhost:8080/api/me/tokens \
  -H "Content-Type: application/json" \
  -H "X-Scrumboy: 1" \
  -d '{"name":"cli"}'

Response includes a one-time token (starts with sb_).

Use it with MCP:

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sb_your_token_here" \
  -d '{"tool":"projects.list","input":{}}'

Code layout (reference)

• cmd/scrumboy: main server entrypoint. Other cmd/* are utilities (tagcheck, tagrecover, dbquery, slugfix).
• internal/config: env-based config.
• internal/version: app and export format version.
• internal/db: SQLite open/options (PRAGMAs from config).
• internal/migrate: DB migrations.
• internal/store: data model and persistence (projects, todos, tags, auth, backup, ordering, memberships, audit, links, sprints, workflows, etc.).
• internal/httpapi: HTTP server, routing, auth cookies, SPA serve, embedded web FS.
• internal/httpapi/web: frontend (TS, CSS, HTML); built with npm run build in internal/httpapi/web; output under web/dist and embedded by server.

Invariants (e.g. canonical URL /{slug}, no UI links to /p/{id}) are enforced in code and tests; see internal/httpapi and internal/store for the authoritative behavior.

---