# Install with Docker

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

> For the complete documentation index, see [llms.txt](https://helpdesk.orangescrum.com/llms.txt).

Source: https://helpdesk.orangescrum.com/guide/community/install/docker

---
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](https://helpdesk.orangescrum.com/guide/community/install/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](https://helpdesk.orangescrum.com/guide/community/install/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](https://helpdesk.orangescrum.com/guide/community/install/install-wizard): Create the database schema and your admin account.