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)
• redis-cli for the fastest connection check
• Local ports available for RESP and Postgres (examples use 6379 and 5432)

Pull the image

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

docker pull asamsig/pg_resp:latest

The image ships Postgres with pg_cron, pg_prewarm, pg_resp, and pg_resp_gw_host already installed. 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 pg_resp \
  -p 6379:6379 \
  -p 5432:5432 \
  -e POSTGRES_USER=redis \
  -e POSTGRES_PASSWORD=redis \
  -e POSTGRES_DB=pg_resp \
  -e USERNAME=redis \
  -e PASSWORD=redis \
  asamsig/pg_resp:latest

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

Set credentials at container create (DocumentDB-style): POSTGRES_USER / POSTGRES_PASSWORD create the Postgres role; USERNAME / PASSWORD are the gateway + Redis AUTH identity and should match. Defaults are redis / redis / database pg_resp. Changing them later does not rewrite an existing data directory.

Verify the container

docker ps --filter "name=pg_resp"

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:

redis-cli -p 6379 -a redis --no-auth-warning PING
# PONG

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

Client auth is on by default. Use -a / AUTH, or set REQUIRE_CLIENT_AUTH=false for open access. 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 pg_resp \
  -p 6379:6379 \
  -p 5432:5432 \
  -e POSTGRES_USER=redis \
  -e POSTGRES_PASSWORD=redis \
  -e POSTGRES_DB=pg_resp \
  -v pg_resp_data:/var/lib/postgresql \
  asamsig/pg_resp: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 pg_resp \
  -p 6379:6379 \
  -p 5432:5432 \
  -e POSTGRES_USER=redis \
  -e POSTGRES_PASSWORD=redis \
  -e POSTGRES_DB=pg_resp \
  -e PG_RESP_STORAGE_MODE=logged \
  asamsig/pg_resp:latest

Useful knobs:

With compose / make postgres-up, autoprewarm is on by default. Disable with PG_PREWARM_AUTOPREWARM=off (see Buffer cache prewarm).

Full map: Configuration. If you change PG_RESP_PORT, publish that container port with -p as well.

Stop and remove

docker stop pg_resp
docker rm pg_resp

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 pg_resp.
• 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