Configuration

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

The application reads its settings from environment variables. In Docker, set them in a .env file beside docker-compose.yml - copy .env.example to .env and edit it. Do not edit docker-compose.yml; every value there already reads from the environment. For a manual install, set them in the web server or shell environment.

#Core variables

Variable	Purpose	Docker default
`APP_PORT`	Host port the app is published on	`8080`
`DB_HOST`	PostgreSQL host (fixed on Docker)	`orangescrum-postgres`
`DB_PORT`	PostgreSQL port	`5432`
`DB_NAME`	Database name	`orangescrum`
`DB_USERNAME`	Database user	`orangescrum`
`DB_PASSWORD`	Database password	`orangescrum`
`FULL_BASE_URL`	Public URL of the instance	`http://localhost:8080`
`CACHE_ENGINE`	Cache backend	`file`
`SESSION_COOKIE_SECURE`	Require HTTPS for session cookies	`false`
`SESSION_COOKIE_NAME`	Session cookie name	`ORANGESCRUM_SESSID`
`SESSION_COOKIE_DOMAIN`	Cookie domain; empty means this host only	(empty)
`CSRF_COOKIE_NAME`	CSRF cookie name	`orangescrum_csrf`
`SECURITY_SALT`	Salt for hashing, CSRF and sessions	(empty: generated per install)
`SHOW_UPGRADE_CTA`	Show the in-app Upgrade and Add-ons pages	`true`

#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

💾Backup and restore

Set this up before you have data worth losing.