# Configuration

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

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

Source: https://helpdesk.orangescrum.com/guide/self-hosted/install/configuration

---
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](https://helpdesk.orangescrum.com/guide/self-hosted/install/installer). 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
```

```bash
sudo systemctl restart php8.2-fpm
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](https://helpdesk.orangescrum.com/guide/self-hosted/operate/backup): Before the instance carries anything you cannot lose.