Skip to content

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.30.0.1
DB_PORT=5432

172.30.0.1 is the gateway of trapper_network, the bridge subnet trapper-setup pins in docker-compose.yml (TRAPPER_NETWORK_SUBNET, default 172.30.0.0/16) — use it when Postgres runs on the same machine, outside Docker. If you've overridden TRAPPER_NETWORK_SUBNET/TRAPPER_NETWORK_GATEWAY, use your own gateway IP instead. trapper-setup's wizard exposes external-DB mode as USE_EXTERNAL_POSTGRES=true.

Docker Desktop (macOS/Windows)

The gateway-IP trick only works with Docker Engine on Linux. Under Docker Desktop, containers can't reach the host via the bridge gateway — use DB_HOST=host.docker.internal instead (and skip the subnet-based pg_hba.conf range below in favour of the host's own address).

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.30.0.0/16   scram-sha-256

172.30.0.0/16 matches trapper_network's default subnet (TRAPPER_NETWORK_SUBNET in trapper-setup/docker-compose.yml) — adjust if you've overridden it. Tighten the address range further where possible (e.g. the gateway's /32), and confirm the target server supports scram-sha-256 (PostgreSQL 10+; default since PostgreSQL 14).

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.