A Reproducible Docker Development Environment

A good development environment makes PostgreSQL, pgvector, migrations, fixtures, and tests repeatable without pretending a laptop is production. Pin image and dependency versions, expose the database only on loopback, use health checks, keep secrets outside Git, run migrations explicitly, and provide one command to start, verify, test, inspect, and remove the stack.

What will you be able to do?

Compose a database and application development stack.
Separate migrations from normal application startup.
Seed deterministic retrieval fixtures.
Add health and readiness checks.
Remove containers and named data deliberately.

What should the stack contain?

yaml

services:
  db:
    image: pgvector/pgvector:pg18
    env_file: .env.local
    ports: ["127.0.0.1:5432:5432"]
    volumes: ["pgdata:/var/lib/postgresql/data"]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 3s
      timeout: 3s
      retries: 20
  api:
    build: .
    env_file: .env.local
    depends_on:
      db:
        condition: service_healthy
    ports: ["127.0.0.1:8000:8000"]

volumes:
  pgdata:

Pin the application base image and lock dependencies. Do not bake .env.local into the image. Use separate commands or profiles for migrations, fixtures, workers, and evaluation.

What makes fixtures useful?

Seed two tenants, authorized and unauthorized documents, exact identifiers, paraphrases, multilingual text, duplicate chunks, deleted rows, and deterministic small vectors. Fixtures should test behavior rather than imitate model quality. A separate optional integration dataset can use the real embedding provider.

What should readiness prove?

Container process health is insufficient. The API readiness check should confirm database connectivity, required schema migration, vector extension/version compatibility, and critical configuration. It should not call an expensive generation provider on every probe.

How do you verify it?

On a clean machine or CI runner: copy an example env file, start, wait for health, run migrations, load fixtures, run tests, restart, run tests again, then remove. Confirm extension version and no secret in images or Git history.

bash

docker compose down

The following command also deletes this Compose project's named development volume. Confirm the project before running it:

bash

docker compose down --volumes

What breaks in production?

latest changes the database under developers.
App startup races or silently runs migrations concurrently.
Host-mounted code or credentials enter production images.
Health checks pass before schema compatibility.
Cleanup removes the wrong Compose project's volume.

AI pair-work prompt

Review this Docker pgvector development stack [paste]. Check pinned versions, loopback ports, health/readiness, secrets, migration ownership, deterministic fixtures, non-root app user, image contents, resource limits, restart behavior, and scoped cleanup.

Verification contract: Recreate from a clean checkout using documented commands and produce PostgreSQL, pgvector, migration, and test evidence without manual database edits.

Check your understanding

Why should migrations be explicit?
What does a readiness check prove beyond process health?
Which command deletes the named development data, and why is it deliberate?

Official references

A Reproducible Docker Development Environment

What should the stack contain?

yaml

services:
  db:
    image: pgvector/pgvector:pg18
    env_file: .env.local
    ports: ["127.0.0.1:5432:5432"]
    volumes: ["pgdata:/var/lib/postgresql/data"]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 3s
      timeout: 3s
      retries: 20
  api:
    build: .
    env_file: .env.local
    depends_on:
      db:
        condition: service_healthy
    ports: ["127.0.0.1:8000:8000"]

volumes:
  pgdata:

Pin the application base image and lock dependencies. Do not bake .env.local into the image. Use separate commands or profiles for migrations, fixtures, workers, and evaluation.

What makes fixtures useful?

How do you verify it?

bash

docker compose down

The following command also deletes this Compose project's named development volume. Confirm the project before running it:

bash

docker compose down --volumes

AI pair-work prompt

Review this Docker pgvector development stack [paste]. Check pinned versions, loopback ports, health/readiness, secrets, migration ownership, deterministic fixtures, non-root app user, image contents, resource limits, restart behavior, and scoped cleanup.

Verification contract: Recreate from a clean checkout using documented commands and produce PostgreSQL, pgvector, migration, and test evidence without manual database edits.