Getting started

This walkthrough takes you from a fresh install to your first share link.

1. Run StateBoard

For a local spin-up, the repo ships a docker-compose.yaml with Postgres and a pre-seeded Keycloak (test users alice / bob, password = username):

cp .env.example .env
docker compose up -d        # Postgres + Keycloak
pnpm install
pnpm migrate                # create the tables
pnpm dev

Open http://localhost:3000 and click Open boards. You'll be sent to sign in: choose Continue with Keycloak and log in as alice — the first sign-in becomes the workspace owner.

For a real deployment (your own Keycloak, via Docker Compose or Helm), see Self-hosting.

2. Create a board

On /boards, click New board. Give it a name, usually a product or a quarter, e.g. Acme Dashboard / Q2. The description is optional.

Already have a board that's close to what you need? Click Duplicate on its card to deep-copy every screen and region into a new board, then swap only the screens that changed — faster than starting over.

Each board has:

• An internal id used in the editor URL (/boards/{id}).
• A public slug used in the share link (/share/{slug}).

Different URLs on purpose: the editor URL is yours, the share URL is what you hand to stakeholders.

3. Upload a screen

Inside your board, drop a screenshot onto the upload area or click to browse. Allowed formats: PNG, JPEG, WebP, GIF. Max 25 MB per file.

You can upload as many screens as you want. They appear as tabs. Drag a tab to reorder them; the order carries through to the share view and Present mode.

4. Mark your first region

With a screen open, click and drag anywhere on the image to draw a rectangle. When you release, a side panel slides in. Pick a state, give the region a label, optionally add notes.

Three states only, by design:

• Shipped · live, real data, fully wired up.
• Mock · UI is in place but data is hardcoded or fake.
• Missing · not built yet.

Press Esc at any time to discard a draft region.

5. Share it

Click Share in the header to copy the read-only URL. Or open the public view in a new tab with the arrow icon next to it.

That URL is the artifact. Hand it to your exec, your designer, your investor (anyone who's about to ask "so what's working right now?") and they'll get the answer in seconds without needing a Jira tour.

What's next

• Annotate like you mean it: when to use each state, label conventions, notes that actually help.
• Use Present mode: go fullscreen for a stakeholder review.
• Self-host on your cluster: Helm, Docker, airgap configurations.