Docker Quick Start

Run PostRESP locally with Docker — Postgres and the in-process RESP gateway in one image.

Run PostRESP locally with Docker and verify the setup before moving to client code.

The image is a single-instance Postgres + RESP stack (default unlogged storage). It is not an HA / replicated deployment — unlogged is not replicated; use logged for Postgres HA. See Storage modes › HA and clustering.

Prerequisites

• Docker (or a Docker-compatible engine such as Podman)
• Local ports available for RESP and Postgres (examples use 6379 and 5432)
• Optional: a host redis-cli — the image also ships redis-cli for in-container checks

Pull the image

If you do not already have the image locally, pull it first:

docker pull asamsig/postresp:latest

The published image is asamsig/postresp. Inside it, the Postgres extensions remain pg_resp / pg_resp_gw_host (plus pg_cron and pg_prewarm). On first start, init scripts create the extensions and the in-process RESP gateway listens on 6379.

Two supporting extensions run by default:

• pg_cron — schedules active TTL deletion so expired keys are removed in the background (lazy expiry on access still applies). See Commands › TTL.
• pg_prewarm — autoprewarm is on, so recently used pgresp.* data is loaded back into Postgres memory after restart. See Buffer cache prewarm.

Start PostRESP

docker run -d --name postresp \
  -p 6379:6379 \
  -p 5432:5432 \
  -e POSTRESP_PASSWORD=postresp \
  asamsig/postresp:latest

Map whatever host ports you want — for example -p 5762:6379 if 6379 is taken, then use redis-cli -p 5762.

Set credentials with PostRESP env (Redis/Valkey names also work): -e POSTRESP_PASSWORD=…. If you omit it, the image generates a random secret on first start and prints it once in docker logs. Defaults still create two logins with that secret: postresp (RESP on POSTRESP_DATABASE, default postgres) and postgres (SQL superuser). See Authentication.

Verify the container

docker ps --filter "name=postresp"

You should see the container in an Up state with ports 6379 and 5432 published.

Verify the connection

Use redis-cli to confirm the RESP endpoint (host client, or the copy inside the container):

redis-cli -p 6379 PING
# PONG

# same check from inside the image (also used by the container healthcheck)
docker exec postresp redis-cli -h 127.0.0.1 PING

redis-cli -p 6379 SET session:1 '{"user":"ada"}'
redis-cli -p 6379 GET session:1
# {"user":"ada"}

Wire auth is off by default. To require AUTH, set RequireClientAuth: true (a password alone is not enough). Published -p 6379:6379 with auth off is an open RESP endpoint — see Authentication.

For a fuller shell walkthrough (TTL, lists, SQL peek), continue with the redis-cli Quick Start.

Persistence

The quick start command above is ideal for disposable local environments. When you need data to survive container removal, mount a volume on the Postgres data directory (/var/lib/postgresql — required by Postgres 18+ images; do not use the older /var/lib/postgresql/data mount):

docker run -d --name postresp \
  -p 6379:6379 \
  -p 5432:5432 \
  -e POSTRESP_PASSWORD=postresp \
  -v postresp_data:/var/lib/postgresql \
  asamsig/postresp:latest

If you previously mounted /var/lib/postgresql/data (Postgres 16 image), remove that volume and recreate — majors are not in-place upgradeable via a volume remount.

Storage durability inside Postgres is controlled by StorageMode (unlogged by default). See Storage modes.

Common runtime overrides

Gateway settings can be overridden with environment variables on docker run:

docker run -d --name postresp \
  -p 6379:6379 \
  -p 5432:5432 \
  -e POSTRESP_PASSWORD=postresp \
  -e POSTRESP_STORAGE_MODE=logged \
  asamsig/postresp:latest

Useful knobs:

Autoprewarm is on by default in the compose stack. Disable with PG_PREWARM_AUTOPREWARM=off (see Buffer cache prewarm).

Full map (including Redis/Valkey aliases): Configuration. If you change the RESP port, publish that container port with -p as well.

Stop and remove

docker stop postresp
docker rm postresp

Troubleshooting

If something does not work as expected:

• Confirm port 6379 is available and that docker ps shows the container running.
• Inspect startup errors with docker logs postresp.
• Wait a few seconds after first start — Postgres init and extension create run once before the gateway is ready.
• If PING fails immediately, retry once the logs show the database is ready to accept connections.
• Use the redis-cli Quick Start for a fuller connection walkthrough.

Next steps