Installation guide

Choose one way to install. Each keeps its data in PostgreSQL and can be upgraded in place.

| Windows installer | Windows 11, Windows Server 2022 / 2025 | chips-1.7.0-windows-amd64.zip | | macOS installer script | macOS 12+ on Apple silicon or Intel | chips-1.7.0-macos-arm64.tar.gz, chips-1.7.0-macos-x86_64.tar.gz |

The packages contain CHIPS compiled for that operating system and processor, for Python 3.10–3.13 (see Protected builds); ARM64 Linux packages are named …-linux-aarch64 / …_arm64.deb.

Verify what you downloaded first: sha256sum -c SHA256SUMS.

By installing CHIPS you accept its license agreement; the first administrator accepts it again when setting CHIPS up.

Debian or Ubuntu package

sudo apt install ./chips_1.7.0_amd64.deb

The package installs its dependencies (Python, PostgreSQL), creates the database, the scrumpoker service user and the scrum-poker systemd service, and starts CHIPS on port 8080. Then open http://<server>:8080 and choose Set up CHIPS with the setup code the package printed (see First-time setup). Settings are in /etc/scrum-poker.env (see Configuration).

• sudo apt remove chips removes the application and keeps the database and settings.
• sudo apt purge chips also deletes the database and settings.

Installer script (Linux and macOS)

tar xzf chips-1.7.0-linux-x86_64.tar.gz && cd chips-1.7.0
sudo ./deploy/install.sh          # a macOS package: ./deploy/install.sh (no sudo)

The script supports Debian/Ubuntu (apt) and Fedora/RHEL-family (dnf) hosts with systemd.

sudo ./deploy/install.sh

It installs Python and PostgreSQL, creates a scrumpoker database and role with a random password, copies the app to /opt/scrum-poker, creates a virtualenv, writes /etc/scrum-poker.env and starts the scrum-poker service on port 8080.

At the end it prints a one-time setup code. Open http://<host>:8080, choose Set up CHIPS and enter it: the wizard creates the administrator and stores the installation options (see First-time setup). Then create a project and a room, and share the room's link.

Re-running the script upgrades in place, keeping the database and settings (it also removes the two services used by earlier versions of this project). Everything it adds to the machine is recorded in /var/lib/scrum-poker, so it can be removed cleanly later (see Uninstall).

sudo systemctl status scrum-poker
journalctl -u scrum-poker -f
sudo nano /etc/scrum-poker.env && sudo systemctl restart scrum-poker

Production notes * Set PUBLIC_URL in /etc/scrum-poker.env to the address people use: share links and OAuth redirect URIs are built from it. * STORAGE_SECRET signs browser sessions and also encrypts the Jira tokens and OAuth client secrets stored in the database. Keep it secret; if you change it, people sign in again and saved Jira connections and OAuth client secrets must be entered again. * Put it behind HTTPS when it is reachable beyond a trusted network: deploy/Caddyfile sets up Caddy with an automatic certificate. * Self-registration is off unless the setup wizard turned it on (Admin → Settings). Add people in Admin → Users, or let them sign in with your organisation's OAuth provider. * Behind a reverse proxy on another machine, set FORWARDED_ALLOW_IPS to its address so CHIPS sees the browsers' addresses (for the activity log and for blocking password guessing). * Command-line administration on the host (also a way back in if nobody can sign in): sudo -u scrumpoker bash -c 'set -a; . /etc/scrum-poker.env; cd /opt/scrum-poker; venv/bin/python -m scrumpoker.manage list-users' — commands: create-admin, create-user, set-role, reset-password, enable, disable, list-users, truncate-log, setup-code, unlock, reset-2fa, security-check, license. * GET /healthz returns 200 while the database answers (503 otherwise), for monitoring. * Run a single instance: live updates are delivered within the process.

macOS

Use the macOS package (chips-1.7.0-macos-arm64.tar.gz for Apple silicon, …-macos-x86_64 for Intel).

For macOS 12 or later, on Apple silicon or Intel. Run it as yourself, without sudo:

./deploy/install.sh

On a Mac the same command runs the macOS installer (deploy/macos/install.sh). It:

• uses the PostgreSQL server already running on the Mac (Postgres.app or Homebrew) if there is one; otherwise it installs Homebrew's postgresql@16 and starts it. (If Postgres.app is installed but stopped, it asks you to start it rather than installing a second server.)
• uses Python 3.10 or newer if present, otherwise installs Homebrew's python@3.12
• puts the app, its Python environment, settings and session data in ~/Library/Application Support/ScrumPoker, and its log in ~/Library/Logs/ScrumPoker
• creates the scrumpoker database and role, and starts the app as a background service for your user (launchd job local.scrumpoker) on port 8080

Homebrew (https://brew.sh) is needed only when PostgreSQL or a recent Python has to be installed. Like the Linux installer, it records what it adds, and re-running it upgrades in place.

Things to know when a Mac is the host:

• It runs while you are logged in. For a Mac that should serve the team all day, turn on automatic login (System Settings → Users & Groups) or use a Linux server instead.
• Keep the Mac awake while people are estimating (System Settings → Energy / Battery), or run caffeinate -s in a Terminal window.
• Firewall: if the macOS firewall is on, allow incoming connections for CHIPS's Python (System Settings → Network → Firewall → Options), or other devices cannot connect.
• Share links use the Mac's network address (e.g. http://192.168.1.20:8080); change PUBLIC_URL in ~/Library/Application Support/ScrumPoker/scrum-poker.env to use another address, then restart with launchctl kickstart -k gui/$(id -u)/local.scrumpoker.
• Homebrew's and Postgres.app's PostgreSQL trust every connection from the Mac itself; CHIPS only listens to the network on port 8080.
• Administration commands on the Mac: cd ~/Library/Application\ Support/ScrumPoker/app && (set -a; . ../scrum-poker.env; ../venv/bin/python -m scrumpoker.manage list-users)

Windows

For Windows 11 and Windows Server 2022 / 2025 (x64; Windows on ARM runs the x64 package). Windows 12 has not been released yet; the installer uses only standard Windows and PowerShell features. Unpack chips-<v>-windows-amd64.zip and double-click deploy\windows\install.cmd (it asks for administrator rights), or in an elevated PowerShell:

powershell -ExecutionPolicy Bypass -File deploy\windows\install.ps1      # options: -Port 8080 -DatabaseUrl … -NoFirewall

It:

• uses an installed Python 3.10–3.13 (for all users) and PostgreSQL 13+, or installs Python 3.12 and PostgreSQL 16 with winget (PostgreSQL gets a random superuser password that is used once and not stored; with an existing PostgreSQL it asks for the postgres password, or pass -DatabaseUrl to use any database);
• creates the scrumpoker role and database, copies CHIPS to C:\Program Files\CHIPS\app with its own Python environment, and keeps settings, browser storage and logs in C:\ProgramData\CHIPS — readable only by Administrators, SYSTEM and the service;
• runs CHIPS in the background as LOCAL SERVICE (scheduled task CHIPS, started at boot, restarted if it stops) and opens TCP 8080 in Windows Firewall for domain and private networks (not public ones);
• prints the setup code for the welcome page.

Re-running it upgrades in place. Day to day:

Get-ScheduledTask CHIPS | Start-ScheduledTask            # or Stop-ScheduledTask
Get-Content C:\ProgramData\CHIPS\logs\chips.log -Tail 50 -Wait
notepad C:\ProgramData\CHIPS\chips.env                  # then stop and start the task
C:\"Program Files"\CHIPS\app\deploy\windows\setup-code.ps1     # a new setup code (before the first setup)

To remove it: deploy\windows\uninstall.cmd, or uninstall.ps1 -DryRun | -Backup chips.sql | -KeepData | -RemovePrerequisites | -Yes. It removes the task, the firewall rule, the program and (unless -KeepData) the database and C:\ProgramData\CHIPS; Python and PostgreSQL stay unless -RemovePrerequisites is given and the installer had added them.

Servers without internet access

Use chips-1.7.0-linux-x86_64-offline.tar.gz: it contains a wheelhouse/ with every Python package, and the installer uses it instead of downloading. PostgreSQL and Python come from your distribution's own repositories or mirror.

Docker

docker load < chips-1.7.0-docker.tar.gz        # or build it: docker build -t chips:1.7.0 .
docker compose up -d                                  # from the unpacked chips-1.7.0 folder, with .env

Works on Linux and on macOS with Docker Desktop:

printf 'STORAGE_SECRET=%s\nDB_PASSWORD=%s\nPUBLIC_URL=http://%s:8080\n' \
    "$(openssl rand -hex 32)" "$(openssl rand -hex 24)" "<this machine's address>" > .env
docker compose up -d
docker compose logs app | grep -A1 "setup code"      # then open the address and choose Set up CHIPS

Compose refuses to start without STORAGE_SECRET and DB_PASSWORD. The app container is read-only, drops all Linux capabilities and cannot gain privileges; its browser storage is in the storage volume. A new setup code: docker compose exec app python -m scrumpoker.manage setup-code.

Python package

python3 -m venv /opt/chips && /opt/chips/bin/pip install chips_estimation-1.7.0-*-linux_x86_64.whl
DATABASE_URL=postgresql://user:pass@db/chips STORAGE_SECRET=$(openssl rand -hex 32) \
  PUBLIC_URL=https://chips.example.com /opt/chips/bin/chips          # the setup code is in the output

chips starts the server; chips-manage is the administration command line; chips --version shows the version. Run it under systemd, supervisord or your platform's process manager.

Configuration

Environment variables (in /etc/scrum-poker.env for the installer and the package, .env for Docker):

HTTPS

Put CHIPS behind a reverse proxy with a certificate. A ready Caddy configuration is in deploy/Caddyfile: replace the host name and run Caddy; it obtains a certificate automatically. WebSockets must be passed through (Caddy and recent nginx do this).

Upgrading

Install the new version the same way (re-run the installer, apt install the new package, or pull the new image). The database is upgraded automatically at start-up, in one transaction. Back up first:

sudo -u postgres pg_dump scrumpoker | gzip > chips-backup-$(date +%F).sql.gz

Re-run the installer (sudo ./deploy/install.sh, or ./deploy/install.sh on a Mac). The database is upgraded automatically at start-up, in one transaction:

• scrum master accounts are kept; the oldest becomes the administrator;
• each scrum master's rooms move into a project called "My project";
• votes already cast become round 1 of a session called "Before upgrade", and a vote that was in progress can simply be finished;
• each room's sizing (Fibonacci or t-shirt) becomes its technique, with its numbers kept; new rooms start with planning poker (Admin → Settings → default technique);
• imported Priority, Assignee, Labels and version columns become the stories' attributes;
• the activity log starts empty, with an entry for the start-up; display settings start at their defaults (follow the device, indigo, UTC);
• everyone stays signed in.

Uninstalling

sudo ./deploy/uninstall.sh --dry-run          # see exactly what would be removed; changes nothing
sudo ./deploy/uninstall.sh --backup scrum-poker.sql.gz    # save the data, then remove everything

(On a Mac, run the same commands without sudo; see On macOS below.)

The script lists what it will remove — including how many rooms and stories the database holds — and asks before doing anything. (A copy is also installed at /opt/scrum-poker/deploy/uninstall.sh, so the project folder isn't needed.) It removes:

• the scrum-poker service (and the two services of earlier versions, if present)
• the application in /opt/scrum-poker, including its Python environment and browser-session data
• the scrumpoker database and database role, and the settings file /etc/scrum-poker.env
• the scrumpoker system user, and the install record in /var/lib/scrum-poker
• changes the installer made to PostgreSQL: it is stopped and disabled again if the installer started it, and on Fedora/RHEL its login settings are restored

It only removes what CHIPS's installer created. It leaves alone, and reports: * PostgreSQL, when it also holds other databases or roles, or when it was installed before CHIPS; * packages that other software on the machine still needs (their list is kept, so running uninstall.sh --remove-packages again later finishes the job once nothing needs them); * a scrumpoker user or database that existed before installation; * your Caddy configuration (it tells you if the CHIPS site block is still there) and past log entries in the system journal.

Without --remove-packages, packages are kept: they are common tools that other software may use.

Restoring a backup after reinstalling:

sudo ./deploy/install.sh
sudo systemctl stop scrum-poker
gunzip -c scrum-poker.sql.gz | sudo -u postgres psql -q -o /dev/null -d scrumpoker
sudo systemctl start scrum-poker

On macOS

./deploy/uninstall.sh (as yourself, no sudo) takes the same options and follows the same rules. A copy is kept at ~/Library/Application Support/ScrumPoker/app/deploy/uninstall.sh. It removes:

• the local.scrumpoker background service, the app folder in ~/Library/Application Support/ScrumPoker and the log folder ~/Library/Logs/ScrumPoker
• the scrumpoker database and role, and the settings file
• Homebrew's PostgreSQL service is stopped again if the installer started it
• with --remove-packages: the Homebrew formulae the installer added (PostgreSQL and its dependencies, Python) that nothing else needs, and Homebrew PostgreSQL's data folder if the installer created it and it holds only CHIPS

It never touches Postgres.app or a PostgreSQL that holds other databases, and it reports a macOS firewall rule for CHIPS's Python if one is left, so you can remove it in System Settings.

Restoring a backup on a Mac after reinstalling:

./deploy/install.sh
launchctl bootout gui/$(id -u)/local.scrumpoker
gunzip -c scrum-poker.sql.gz | psql -h localhost -q -o /dev/null -d scrumpoker
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/local.scrumpoker.plist

(With Homebrew's PostgreSQL, psql is in $(brew --prefix postgresql@16)/bin.)

Docker and development setups

Docker: ./deploy/uninstall.sh --docker (add --backup FILE or --keep-data as above), run from the project folder. The shared postgres:16 base image is left for other projects; remove it with docker image rm postgres:16 if nothing else uses it.

Development setup: delete the virtual environment and session data, and drop the databases: rm -rf venv .nicegui && dropdb scrumpoker && dropdb scrumpoker_test.