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/opensource-community-edition.git
cd opensource-community-edition

Optional: set your own values
The defaults work without any change. To use a different port, public URL or database password, copy the example file and edit it:
bash
```
cp .env.example .env
```
Docker Compose reads .env on its own. See Configuration for every value.
Set SECURITY_SALT before the first start
A fixed SECURITY_SALT in .env keeps login sessions valid across rebuilds. Without it, a rebuild can sign everybody out. Generate one with openssl rand -hex 32.
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:8080 (or the APP_PORT you set). 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, published on host port `8080`
`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

dotenv

APP_PORT=8080
FULL_BASE_URL=http://localhost:8080
DB_NAME=orangescrum
DB_USERNAME=orangescrum
DB_PASSWORD=orangescrum
CACHE_ENGINE=file
SESSION_COOKIE_SECURE=false
SESSION_COOKIE_NAME=ORANGESCRUM_SESSID
SESSION_COOKIE_DOMAIN=
CSRF_COOKIE_NAME=orangescrum_csrf
SHOW_UPGRADE_CTA=true
# SECURITY_SALT=

DB_HOST is always orangescrum-postgres and DB_PORT is always 5432, because both containers sit on the same Compose network.

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.

SESSION_COOKIE_DOMAIN is empty by default, which scopes the cookie to the exact host. Set it with a leading dot, for example .example.com, only when you must share the session across subdomains.

#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

8080 is the host-side port. Nothing in docker-compose.yml is hard-coded, so do not edit that file. Set the port in .env instead:

dotenv

APP_PORT=9000
FULL_BASE_URL=http://localhost:9000

Then 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.

#If it doesn't come up

Port 8080 already in use

Something else holds the port. Set a different APP_PORT in .env, or stop the other process. On Windows, check with netstat -ano | findstr 8080.

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.