External database¶

At a glance

Point a TRAPPER Expert deployment at an external PostgreSQL server (RDS, on-prem, …) instead of the bundled container.

Time: ~10 minutes
Who: operators of production/staging deployments
Prerequisites: a reachable PostgreSQL server with superuser access to install extensions

Before you begin¶

PostGIS extension available on the target server (always required)
TimescaleDB extension available — always required, the ObjectFrameObservation hypertable has no opt-out (see Frame hypertable)
Network access from the Docker host to the database server

Steps¶

1. Set the connection variables¶

DB_NAME=trapper
DB_USER=trapper
DB_PASS=trapper
DB_HOST=172.17.0.1
DB_PORT=5432

172.17.0.1 is the Docker bridge gateway on most Linux hosts — use it when Postgres runs on the same machine, outside Docker. trapper-setup's wizard exposes this as USE_EXTERNAL_POSTGRES=true.

2. Prepare the external server¶

Requirement	Why
PostGIS extension	Always required — spatial queries on locations/deployments
TimescaleDB extension	Always required — no opt-out
`listen_addresses = '*'` in `postgresql.conf`	Accept connections from the Docker host
Permissive `pg_hba.conf` entry	Allow the Docker host's network range

# TYPE   DATABASE   USER   ADDRESS       METHOD
host     all        all    172.0.0.0/8   md5

Tighten the address range as appropriate for your network — 172.0.0.0/8 is a starting point for Docker bridge networking, not a production-ready rule.

3. Sanity-check the connection¶

psql -h <host> -U trapper -d trapper

Do this before starting the stack — a failed connection at container startup is harder to diagnose than a failed psql.

4. Start the stack¶

Follow Deploy with trapper-setup as usual — the wizard renders the external-DB settings into .env when USE_EXTERNAL_POSTGRES=true.

Verify it worked¶

The Expert container should start without database connection errors. Check ./profiles/<profile>/logs.sh trapper for connection refused / password authentication failed if it doesn't.

Troubleshooting¶

Connection refused

Check listen_addresses and that the port is reachable from inside the Docker network (./profiles/<profile>/exec.sh trapper bash then psql -h <host> ...).

Missing extension errors on migrate

Connect as a superuser and run CREATE EXTENSION IF NOT EXISTS postgis; and CREATE EXTENSION IF NOT EXISTS timescaledb; — both are required, migrations don't run without them.