# Configuration

> Environment variables, mail, sessions and the settings to change before you expose an instance.

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

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

---
The application reads its settings from environment variables. In Docker these
live in `docker-compose.yml`; for a manual install, set them in the web server
or shell environment.

## Core variables

| Variable | Purpose | Docker default |
| --- | --- | --- |
| `DB_HOST` | PostgreSQL host | `orangescrum-postgres` |
| `DB_NAME` | Database name | `orangescrum` |
| `DB_USERNAME` | Database user | `orangescrum` |
| `DB_PASSWORD` | Database password | `orangescrum` |
| `FULL_BASE_URL` | Public URL of the instance | `http://oss.localhost:8091` |
| `CACHE_ENGINE` | Cache backend | `file` |
| `SESSION_COOKIE_SECURE` | Require HTTPS for session cookies | `false` |
| `SESSION_COOKIE_NAME` | Session cookie name | `OSS_SESSID` |
| `SESSION_COOKIE_DOMAIN` | Cookie domain | `oss.localhost` |
| `CSRF_COOKIE_NAME` | CSRF cookie name | `oss_csrfToken` |

### FULL_BASE_URL

Every generated link — invitations, password resets, notification emails — is
built from this. It must match the address people actually type, including
scheme and port.

```yaml
FULL_BASE_URL: https://orangescrum.example.com
```

> **A mismatch breaks invitations silently**
>
> The app keeps working; only the links in emails point somewhere wrong. Set
> this correctly before inviting anyone.

## Before you go live

The shipped defaults are tuned for plain-HTTP localhost development. Four things
must change:

**Change the database password**

    `orangescrum` is published in the repository. Set a strong password in both
    the `orangescrum-postgres` service and the app's `DB_PASSWORD`, then
    recreate both containers.

**Turn on secure cookies**

```yaml
SESSION_COOKIE_SECURE: "true"
```

    This is `false` by default *because* the default deployment is plain HTTP.
    Once you are behind TLS, flip it — otherwise the session cookie can travel
    unencrypted.

**Set the real base URL and cookie domain**

```yaml
FULL_BASE_URL: https://orangescrum.example.com
SESSION_COOKIE_DOMAIN: orangescrum.example.com
```

**Terminate TLS**

    Put Nginx, Caddy or a load balancer in front, or use Certbot directly on a
    manual install.

> **Do not skip these**
>
> Publishing the default compose file to the internet exposes a database with a
> known password and sends session cookies over plain HTTP.

## Email

Without SMTP, invitations, password resets and notifications are never
delivered. Configure it early — a broken password reset is discovered at the
worst possible moment.

| Variable | Example |
| --- | --- |
| `EMAIL_HOST` | `smtp.example.com` |
| `EMAIL_PORT` | `587` |
| `EMAIL_USERNAME` | `notifications@example.com` |
| `EMAIL_PASSWORD` | your SMTP password |
| `EMAIL_FROM` | `notifications@example.com` |

Send a test by triggering a password reset for an account you control, then
check the log:

```bash
docker compose exec orangescrum-app tail -50 logs/error.log
```

> **Use a real relay**
>
> Mail sent directly from a random VPS is usually filed as spam. Use a
> transactional provider or your organisation's relay, and set SPF and DKIM.

## Caching

`file` is the default and fine for a single server. Clear the cache after any
configuration change:

```bash
docker compose exec orangescrum-app php bin/cake.php cache clear_all
```

> **Tip**
>
> If a setting seems not to apply, clear the cache before assuming the change
> did not take.

## Attachment storage

Uploads go to `webroot/files`, backed by the `orangescrum-app-files` volume in
Docker. This grows without bound — it is the volume to watch, and the one your
backups must include.

## Applying changes

```bash
docker compose up -d --force-recreate orangescrum-app
docker compose exec orangescrum-app php bin/cake.php cache clear_all
```

```bash
sudo systemctl restart php8.2-fpm
php bin/cake.php cache clear_all
```

- [Backup and restore](https://helpdesk.orangescrum.com/guide/community/operate/backup-and-restore): Set this up before you have data worth losing.