Configuration

Domain, TLS, firewall, SMTP and secrets — what to set before an instance goes live.

The installer gets the application running. These are the things that make it safe and usable.

#Domain and TLS

Point a domain at the server
Generated links — invitations, password resets, notifications — are built from the configured base URL. If it disagrees with the address people actually use, the application still works but every emailed link goes somewhere wrong.
Terminate TLS in front of the app
Nginx, Apache, Caddy or a load balancer. The application listens on plain HTTP inside the network; 443 is what you expose.
bash
```
sudo certbot --nginx -d orangescrum.example.com
```
Automate renewal
An expired certificate takes the whole instance offline. Confirm the renewal timer is active, not just that the certificate installed.

#Firewall

Port	Rule
80 (HTTP)	Open — redirect to HTTPS
443 (HTTPS)	Open
5432 (PostgreSQL)	Internal network only
8080 (app)	Internal only — reached through the proxy
8088 (Superset)	Internal only, or restricted to admins

bash

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw deny 5432/tcp

Never expose the database or the raw app port

Publishing 5432 is the most damaging misconfiguration on a self-hosted install. Publishing 8080 bypasses your TLS termination and serves the app in the clear.

#SMTP

Configured during installation. Without it, invitations and password resets are never delivered — and the failure is silent from the sender's point of view.

Setting	Example
Host	`smtp.example.com`
Port	`587`
Username	`notifications@example.com`
Password	your SMTP password
From address	`notifications@example.com`

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 VPS is usually filed as spam. Use a transactional provider or your organisation's relay, and publish SPF and DKIM records.

To change SMTP after installation you edit a server config file — it is not exposed in the admin UI. Plan for that when handing over to a team that expects to self-serve.

#Secrets

Service credentials live as plaintext files in ./secrets/:

File	Used by
`postgres_password.txt`	Main database
`reports_admin_user.txt`	Reports service
`reports_admin_email.txt`	Reports service
`reports_admin_password.txt`	Reports service

Change every default before going live
Anything shipped as an example is public knowledge.
Restrict filesystem access
chmod 600 and owned by the account that runs the stack.
Never commit them
Add secrets/ to .gitignore. Backups of this directory are archives of live passwords — encrypt them.

#Storage

Attachments accumulate under the app-files volume (webroot/files). This is the volume that fills the disk on every long-running install.

📈Monitor it

Alert at 80%. docker system df -v shows per-volume usage.

💾Extend it

A NAS can be mounted to expand capacity beyond the initial allocation.

#Background jobs

Daily Catch-Up digests and task reminders are delivered by scheduled jobs, not by the web request. They live outside the container, in host cron.

Cron is easy to lose in a migration

If digests and reminders stop after a server move, the scheduler is the first thing to check — the records will look correct in the database because storing them and delivering them are separate steps.

#Applying changes

bash

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

Tip

If a setting appears not to apply, clear the cache before assuming the change did not take.

💾Next: backup

Before the instance carries anything you cannot lose.