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:
cd /opt/broadcast
./broadcast.sh restart
Examples
Setting or overriding a single value needs no special syntax — your value simply replaces the stock one:
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):
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:
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:
- Copy your changes into
/opt/broadcast/docker-compose.override.yml(remember the!overridetag when replacing list entries). - Discard the edits to Broadcast’s files:
git -C /opt/broadcast checkout -- .
- Confirm updates flow again and apply your override:
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 for the commands used above, and Upgrading for what happens during an upgrade.
