Scrumboy

Self-hosted project management & issue-tracking solution + instant shareable & customizable boards + realtime collaboration, automation, API access and MCP-compatible client support

Table of contents

• Quick Start
  • Run with Docker
  • Run from source
• Optional Configuration
  • Environment variables
  • Encryption key (optional)
  • OIDC / SSO login (optional)
  • TLS / HTTPS (optional)
  • PWA / Web Push (optional)
  • Frontend build note
• Why Scrumboy?
• Who is this for?
• Modes
• Features
• Integrations & API Access
  • MCP (JSON-RPC) for AI agents
  • Webhooks (outbound HTTP)
• Config
• Roles
  • System roles (instance-wide)
  • Project roles (per project)
• Export scope
• Import modes
• Code layout (reference)
• Documentation
• License and Contributions

Quick Start

Runs in seconds. No setup required.

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

Run with Docker

docker compose up --build

Open http://localhost:8080.

Run from source

go run ./cmd/scrumboy

Open http://localhost:8080.

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.

Encryption key for 2FA/password reset

• SCRUMBOY_ENCRYPTION_KEY is not required for basic startup.
• It becomes required for encrypted auth/security features, including:
  • 2FA
  • Password reset flows
• If an existing database already has 2FA-enabled users, startup fails without this key.
• The key is part of the same backup/restore unit as data/app.db. Back them up together.
• Do not regenerate or replace the key casually after encrypted auth/security data exists, or you can break access to 2FA/password-reset data.

Generate a key with: openssl rand -base64 32

Example for Docker Compose secret injection:

services:
  scrumboy:
    environment:
      - SCRUMBOY_ENCRYPTION_KEY=${SCRUMBOY_ENCRYPTION_KEY}

Example for systemd secret injection:

[Service]
Environment="SCRUMBOY_ENCRYPTION_KEY=REPLACE_WITH_BASE64_32_BYTE_KEY"

In both cases, the deployment manager is injecting the environment variable. Scrumboy itself does not auto-load these files.

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 settin

... View full README on GitHub