Skip to content

Installation ​

This guide sets up the OpenSCRUM Community edition on your own server using Docker. It runs two containers: the OpenSCRUM app and a PostgreSQL database.

What you need ​

  • A machine with Docker and Docker Compose (included with Docker Desktop and current Docker Engine packages).
  • The OpenSCRUM source code. There is no pre-built image yet, so Docker builds the app from source the first time you start it.

1. Get the source code ​

Clone the OpenSCRUM repository and move into its folder:

bash
git clone https://github.com/sammhill/OpenSCRUM.git
bash
cd OpenSCRUM

The remaining commands are run from this folder, which contains docker-compose.yml.

2. Create the settings file ​

Create a file named .env in that folder with at least an AUTH_SECRET. This is a random value used to protect sign-in sessions.

On Linux or macOS:

bash
echo "AUTH_SECRET=$(openssl rand -base64 32)" > .env

On any system with Docker, you can generate a value like this and paste it into .env as AUTH_SECRET=<value>:

bash
docker run --rm node:26-alpine node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

Before the first start, also add these to .env if they apply to you:

ini
# Required if people will open OpenSCRUM at anything other than http://localhost:3000
PUBLIC_URL=https://scrum.example.com

# Recommended: your own database password
POSTGRES_PASSWORD=choose-a-long-random-password

Set the database password before the first start

POSTGRES_PASSWORD is only applied when the database is first created. Changing it in .env later will stop the app connecting unless you also change the password inside PostgreSQL.

See Configuration for every setting.

3. Start OpenSCRUM ​

bash
docker compose up -d

The first start takes a few minutes while the app is built. The database tables are created automatically.

4. Create the first account ​

Open http://localhost:3000 (or your PUBLIC_URL) and choose Create an account. The first account becomes the owner of your organisation, and sign-up then closes to everyone without an invitation. See Accounts and organisations.

Do this straight away: until the first account exists, anyone who can reach the address could create it.

HTTPS on your own domain ​

To put OpenSCRUM on the internet at your own address, switch on the built-in HTTPS option. It adds Caddy, a web server that sits in front of OpenSCRUM, obtains a certificate for your domain from Let's Encrypt and renews it without any further work from you.

You need:

  • A domain name (for example scrum.example.com) whose DNS record points at your server.
  • Ports 80 and 443 on the server reachable from the internet. Port 80 is needed to obtain the certificate even though the site itself is served on 443.
  • Docker Compose 2.24 or newer (docker compose version shows yours).

Then:

  1. Add these two lines to .env, with your own address:
ini
PUBLIC_URL=https://scrum.example.com
COMPOSE_FILE=docker-compose.yml:docker-compose.https.yml
  1. Start (or restart) OpenSCRUM:
bash
docker compose up -d

The first start can take up to a minute while the certificate is issued. After that, open your https:// address.

What this changes:

  • Requests to http:// are redirected to https://.
  • OpenSCRUM is no longer reachable directly on port 3000, only through Caddy.
  • Every other command in this documentation stays the same, because COMPOSE_FILE tells Docker Compose to include the HTTPS option each time.

On a Windows server

Separate the two file names with a semicolon instead of a colon: COMPOSE_FILE=docker-compose.yml;docker-compose.https.yml.

Using your own reverse proxy instead ​

If you already run a reverse proxy (such as nginx or Traefik), leave the HTTPS option off and point your proxy at port 3000.

  • Set PUBLIC_URL to the exact address people use, including https://. Sign-in is refused if it does not match.
  • The proxy must forward WebSocket connections, which OpenSCRUM uses for live updates.

Outbound access ​

To import from Jira or Linear, the server needs outbound HTTPS access to those services. See Jira and Linear.

Stopping and starting ​

bash
docker compose stop
bash
docker compose start

OpenSCRUM starts again by itself if it crashes or the server reboots, unless you stopped it yourself.

Your data is kept in a Docker volume named db-data and survives restarts. Running docker compose down -v deletes that volume and all your data.