Administrator guide

First-time setup

A new installation has no accounts. The welcome page shows the full title and Set up CHIPS, which opens the wizard at /setup:

1. Setup code — a one-time code that proves you installed CHIPS. The installers print it; it is in the server log at every start until setup is done (journalctl -u scrum-poker, docker compose logs app, ~/Library/Logs/ScrumPoker/scrum-poker.log); python -m scrumpoker.manage setup-code (Linux: sudo /opt/scrum-poker/deploy/setup-code.sh) makes a new one. Valid 24 hours, 10 tries; only its hash is stored. The step shows the server checks (database, secret, HTTPS, cookies, integrity).
2. License agreement — accepted and recorded.
3. Administrator — username, display name, email, password (policy applied).
4. Installation options — organisation name, public address, default time zone, language (American or British English spelling), two-factor sign-in for administrators (on by default), self-registration (off by default), password length, sign-in lifetime, people per room, default technique, activity log retention and room logging, REST API, Jira.
5. License key — optional; Community without one.
6. Review and install — saved in one transaction, logged, and you are signed in.

All options can be changed later under Admin → Settings. Installations that already had accounts when upgrading count as set up. create-admin on the command line also still works.

Afterwards:

1. If two-factor sign-in is required for administrators, set it up under Account → Two-factor sign-in — administration stays locked until you do.
2. Install your license key under Admin → License if you did not in the wizard.
3. Add scrum masters under Admin → Users, or let them sign in through your organisation's identity provider (Admin → Sign-in providers, Enterprise).
4. Check Admin → Settings → Security and installation checks, and put CHIPS behind HTTPS.

Day-to-day

The command line

On the server (as the service user, with the settings loaded), python -m scrumpoker.manage — or chips-manage for the Python package:

create-admin NAME                 create-user NAME [--role admin] [--email E] [--no-password]
set-role NAME admin|scrum_master  reset-password NAME        enable NAME / disable NAME
list-users                        version                    init-db
license show | install KEY | remove
truncate-log --all | --older-than DAYS | --before YYYY-MM-DD

These work even when nobody can sign in.

Backups and restore

Everything is in the PostgreSQL database, plus the settings file.

sudo -u postgres pg_dump scrumpoker | gzip > chips-$(date +%F).sql.gz          # back up
gunzip -c chips-2026-10-22.sql.gz | sudo -u postgres psql scrumpoker            # restore into an empty database

Keep STORAGE_SECRET with the backup: without it, saved Jira tokens and OAuth client secrets cannot be read (people would need to enter them again).

Monitoring

• GET /healthz returns {"ok": true, "version": "…"} when CHIPS and its database work (503 otherwise).
• Logs: journalctl -u scrum-poker (Linux), ~/Library/Logs/ScrumPoker/ (macOS), docker compose logs. Activity log entries are also written there.

The first account on a new installation is an administrator (on an upgraded installation, the oldest account is). Admin has tabs for:

• Users — add people (with a password, or without one if they sign in through OAuth), change roles, disable accounts, set passwords, sign someone out everywhere, delete accounts (users who own projects hand them over first). There is always at least one active administrator.
• Projects & rooms — every project with its rooms: rename, give to another user, archive or restore, open any room (you act as its scrum master), delete permanently.
• Sessions — the latest sessions everywhere, with a link to the full history.
• Sign-in providers — OAuth 2.0 / OpenID Connect (below).
• Access tokens — every personal access token, with revoke.
• Settings — self-registration, password sign-in, maximum users per room (≤ 30), session pause length, default sizing, the REST API and Jira on/off, and which Jira servers may be used.

Admin → Sign-in providers → Add. Supported: Google, Microsoft Entra ID (tenant common, organizations or your tenant id), GitHub, Atlassian, any OpenID Connect provider by its issuer URL (Okta, Auth0, Keycloak, Ping, AD FS, …), or any OAuth 2.0 provider by its authorization, token and user-info URLs.

1. Register an application with the provider. Use the redirect URI shown in the form: https://<PUBLIC_URL>/auth/oauth/<short name>/callback.
2. Enter its client ID and secret (the secret is stored encrypted).
3. Choose whether a first sign-in creates a scrum master account, and optionally restrict it to email domains (e.g. example.com). Otherwise an administrator adds the person first (with their email address, no password).

The sign-in button appears on the start page; people who already have an account can also link a provider on their Account page. The flow is the authorization-code flow with PKCE and a state check. An existing account is linked by email only when the provider says the email is verified (never for Microsoft, which does not guarantee it). With password sign-in turned off (Admin → Settings) only administrators can still use passwords — a safety net — and the console refuses to turn passwords off until your own account has a linked provider.

Everything the software does on someone's behalf is logged: sign-ins and sign-outs (and failed attempts), account and administration changes, projects, rooms, stories, voting, notes, imports, Jira, sign-in providers, access tokens, recordings, REST API requests with a refused token, and the software's own start, stop and errors. Each entry records the time, level (info, warning, error), category, who (account, team member, access token or system), the client's IP address, the room, a readable message and details.

Never logged: passwords, tokens, and vote values (the log says that Dana voted, not what) — votes stay secret. Reads (opening pages, downloading) are not logged.

Admin → Activity log shows the newest entries first, 50 per page, with search (text, person, room, IP), filters (category, level, date range), the details of each entry, and Download CSV of what is filtered. Entries also go to the system log (journald, docker logs).

Truncate log… deletes everything, entries older than a number of days, or entries before a date. The truncation is recorded as the first entry of what is left. Under Admin → Settings, Keep log entries for sets automatic retention (default 90 days, 0 = keep until truncated; checked hourly) and Log room activity can leave out votes, notes and board moves.

From the command line (for example from cron):

python -m scrumpoker.manage truncate-log --older-than 30     # or --before 2026-01-01, or --all

The REST API offers GET /api/v1/log and POST /api/v1/log/truncate to administrators.