Install with Docker

Bring up Orangescrum Community Edition and PostgreSQL with a single compose command.

The fastest way to a running instance. The compose file starts two services — the application and PostgreSQL 16 — with persistent volumes for attachments, config and database data.

#Install

Get the source

bash

git clone https://github.com/Orangescrum/orangescrum.git
cd orangescrum

Start the stack
bash
```
docker compose up -d --build
```
The first build pulls base images and compiles assets, so expect several minutes. Later starts are quick.
Watch it come up
bash
```
docker compose ps
docker compose logs -f orangescrum-app
```
The app container has a healthcheck and depends on Postgres being healthy, so it will wait for the database rather than crash-looping.
Open the install wizard
Visit http://localhost:8091. A fresh database redirects you straight to the installer.
Follow Install wizard from here.

#What the compose file gives you

Service	Image	Purpose
`orangescrum-app`	built from `Dockerfile`	The application on port `8091`
`orangescrum-postgres`	`postgres:16`	Database

#Volumes

Data lives outside the containers, so rebuilding the image does not lose it:

Volume	Holds
`orangescrum-app-files`	Task attachments
`orangescrum-app-config`	Generated configuration
`orangescrum-postgres-data`	The database

`docker compose down -v` deletes everything

The -v flag removes those volumes — database, attachments and config. Use plain docker compose down to stop the stack. Only use -v when you genuinely want to start from an empty install.

#Default environment

yaml

DB_HOST: orangescrum-postgres
DB_USERNAME: orangescrum
DB_PASSWORD: orangescrum
DB_NAME: orangescrum
CACHE_ENGINE: file
FULL_BASE_URL: http://oss.localhost:8091
SESSION_COOKIE_SECURE: "false"
SESSION_COOKIE_NAME: OSS_SESSID
SESSION_COOKIE_DOMAIN: oss.localhost
CSRF_COOKIE_NAME: oss_csrfToken

These defaults are for local development

The database password is orangescrum and SESSION_COOKIE_SECURE is explicitly false so session cookies work over plain HTTP on localhost. Both must change before this is reachable from anywhere else — see Configuration.

The cookie names and SESSION_COOKIE_DOMAIN are deliberately distinct so a Community instance on localhost does not clash with any other local app's session.

#Everyday commands

bash

# Stop, keeping all data
docker compose down

# Start again
docker compose up -d

# Follow application logs
docker compose logs -f orangescrum-app

# A shell inside the app container
docker compose exec orangescrum-app bash

# A psql session
docker compose exec orangescrum-postgres psql -U orangescrum -d orangescrum

#Changing the port

8091 is the host-side port. To serve on 8080 instead, edit the mapping:

yaml

ports:
  - "8080:80"

Then update FULL_BASE_URL to match and recreate the container:

bash

docker compose up -d --force-recreate orangescrum-app

Keep FULL_BASE_URL in sync

Generated links — email invitations, password resets — are built from FULL_BASE_URL. If it disagrees with the address people actually use, those links will point at the wrong place.

#Optional: OnlyOffice

An extra compose file ships for document preview:

bash

docker compose -f docker-compose.yml -f docker-compose.onlyoffice.yml up -d

#If it doesn't come up

Port 8091 already in use

Something else holds the port. Change the host side of the mapping, or stop the other process. On Windows, check with netstat -ano | findstr 8091.

App container restarts repeatedly

Check docker compose logs orangescrum-app. Usually the database is not ready yet — the healthcheck retries — or a volume has stale config from a previous install.

Installer reappears after a successful install

The config volume was recreated. Confirm orangescrum-app-config still exists with docker volume ls.

🧙Next: the install wizard

Create the database schema and your admin account.