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-2.2.0-windows-amd64.zip | | macOS installer script | macOS 12+ on Apple silicon or Intel | chips-2.2.0-macos-arm64.tar.gz, chips-2.2.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_2.2.0_amd64.deb

The package installs its dependencies (Python, PostgreSQL, Apache), creates the database, the scrumpoker service user and the scrum-poker systemd service, and puts Apache on port 80 in front of CHIPS. Then open http://<server> 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.
• For HTTPS or an AWS load balancer, run sudo /opt/scrum-poker/deploy/apache.sh with the options in Apache web server and AWS.

Installer script (Linux and macOS)

tar xzf chips-2.2.0-linux-x86_64.tar.gz && cd chips-2.2.0
sudo ./deploy/install.sh          # a macOS package: ./deploy/install.sh (no sudo)
sudo ./deploy/install.sh --with-transcription     # also English transcripts of call recordings

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

sudo ./deploy/install.sh                                                       # HTTP on port 80
sudo ./deploy/install.sh --domain chips.example.com --letsencrypt you@example.com   # HTTPS
sudo ./deploy/install.sh --domain chips.example.com --alb                      # behind an AWS load balancer

It installs Python, PostgreSQL and the Apache web server, 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. CHIPS listens on 127.0.0.1:8080 only; Apache answers on port 80 (and 443) and passes pages and live updates (WebSockets) to it. See Apache web server and AWS. --no-apache leaves Apache out: CHIPS then answers on port 8080 itself. --with-transcription also installs the speech recognition that transcribes English call recordings (see Conference calls).

At the end it prints the address and a one-time setup code. Open the address, 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. * Use HTTPS when it is reachable beyond a trusted network: deploy/apache.sh --domain … --letsencrypt … gets a certificate for Apache, or an AWS load balancer holds one (--alb). * 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 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). deploy/apache.sh sets it for Apache and the AWS load balancer. * 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, transcription. * GET /healthz returns 200 while the database answers (503 otherwise), for monitoring. * Run a single instance: live updates are delivered within the process.

Apache web server and AWS

CHIPS is a Python web application with its own application server (uvicorn), which it needs for live updates. The Apache web server stands in front of it: Apache owns ports 80 and 443, handles HTTPS, and passes every request and the WebSocket connections on to CHIPS on 127.0.0.1:8080, which nobody can reach directly. The installer sets this up with deploy/apache.sh; run that script again at any time to change it (its settings are remembered):

The site is /etc/apache2/sites-available/chips.conf (Debian/Ubuntu) or /etc/httpd/conf.d/chips.conf (RHEL/Amazon Linux); the script also enables the Apache modules it needs (proxy, proxy_http, proxy_wstunnel, headers, rewrite, ssl), switches off Apache's placeholder site, allows Apache to connect to CHIPS under SELinux, and opens ports 80/443 in firewalld or ufw when they are active. It sets HOST, PUBLIC_URL and FORWARDED_ALLOW_IPS in /etc/scrum-poker.env. Logs: /var/log/apache2/chips-*.log (or /var/log/httpd/).

On AWS: allow inbound TCP 80 and 443 in the instance's security group (port 8080 stays closed); behind a load balancer, allow port 80 from the load balancer's security group only. Use a target group of type instance, protocol HTTP, port 80, health check path /healthz (200 = healthy; it reports 503 while the database is unreachable). WebSockets work through the load balancer without extra settings; the default idle timeout of 60 seconds is fine. A complete walk-through, with an EC2 user-data script that installs CHIPS at launch and an optional Amazon RDS database, is in deploy/aws/README.md and in the documentation (Running on AWS).

macOS

Use the macOS package (chips-2.2.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-2.2.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-2.2.0-docker.tar.gz        # or build it: docker build -t chips:2.2.0 .
docker compose up -d                                  # from the unpacked chips-2.2.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-2.2.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

For transcripts of call recordings, also pip install faster-whisper into the same environment.

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

On Linux the installer's Apache front end does this: deploy/apache.sh --domain … --letsencrypt … for a Let's Encrypt certificate, or --alb behind an AWS Application Load Balancer with an ACM certificate (see Apache web server and AWS and Running on AWS). With any other proxy, pass WebSockets through (/_nicegui_ws/), send X-Forwarded-For and X-Forwarded-Proto, and set FORWARDED_ALLOW_IPS to the proxy's address.

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; * Apache itself when other sites use it (only the CHIPS site, and the modules, firewall and SELinux settings the installer changed, are removed), a Caddy configuration from older versions (it tells you if a 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.