# Customizing Docker Services

> Customize Broadcast's Docker services safely with docker-compose.override.yml: change port bindings, environment variables, and resource limits without breaking automatic updates or upgrades.

Source: https://sendbroadcast.net/docs/customizing-docker-services

Broadcast servers run three Docker services (the application, the background
job worker, and PostgreSQL) defined in `/opt/broadcast/docker-compose.yml`.
If you need to adjust how they run (a port binding, an environment variable,
a resource limit), do it through an **override file**, never by editing
Broadcast's own files.

Warning

Never edit `docker-compose.yml` or any other file that ships with Broadcast. Local modifications block the nightly script update and cause upgrades to be refused with an error naming the modified files. Your customizations belong in `docker-compose.override.yml`, which is yours alone and survives every update.

## The override file

Create `/opt/broadcast/docker-compose.override.yml`. Docker Compose merges it
**on top of** the stock `docker-compose.yml` automatically whenever the
services start: you express only your changes, and you keep receiving every
stock configuration improvement Broadcast ships.

Changes take effect on the next restart:

```bash
cd /opt/broadcast
./broadcast.sh restart
```

## Examples

Setting or overriding a **single value** needs no special syntax: your value
simply replaces the stock one:

```yaml
services:
  app:
    environment:
      SOME_SETTING: "value"
```

Replacing an entry in a **list** (like a port binding) needs the
`!override` YAML tag, because Compose merges lists additively by default
(without the tag you would get the stock entry *and* yours):

```yaml
services:
  postgres:
    ports: !override
      - "127.0.0.1:5432:5432"
```

The `!override` tag requires Docker Compose v2.24 or newer, which every
supported Broadcast installation ships.

## Remote database access

If you were about to expose PostgreSQL publicly, use an SSH tunnel instead,
it needs no compose changes, no firewall rules, and no publicly reachable
database port:

```bash
ssh -L 5432:localhost:5432 root@your-server
# then connect your local tools to localhost:5432
```

Warning

Avoid binding PostgreSQL to a public interface or opening port 5432 in the firewall. A database exposed to the internet is one weak password away from a breach; the tunnel gives you the same access with none of the exposure.

## If you already edited docker-compose.yml

A server with hand-edited Broadcast files refuses script updates and upgrades
until the edits are cleared:

1. Copy your changes into `/opt/broadcast/docker-compose.override.yml`
   (remember the `!override` tag when replacing list entries).
2. Discard the edits to Broadcast's files:

   ```bash
   git -C /opt/broadcast checkout -- .
   ```

3. Confirm updates flow again and apply your override:

   ```bash
   cd /opt/broadcast
   ./broadcast.sh update
   ./broadcast.sh restart
   ```

## Good to know

- The override file is reported by `./broadcast.sh diagnose`, so support can
  see your customizations when helping you troubleshoot.
- Upgrades and restarts leave the file untouched: it is yours.
- See the [CLI Reference](https://sendbroadcast.net/docs/cli-reference) for the commands used above,
  and [Upgrading](https://sendbroadcast.net/docs/upgrading) for what happens during an upgrade.