Skip to content
rusthacks.dev
DevOps

Docker Compose for a Rust Service With Postgres and Redis

A Compose file that runs a Rust service with PostgreSQL and Redis for local development, with healthchecks so the app starts after its dependencies, volumes, networks and a clean teardown.

3 min read
Summarize in AI
Flat illustration for the post “Docker Compose for a Rust Service With Postgres and Redis”, composed around database.

A new teammate clones the repository and wants a running system in one command. Compose does that for a Rust service with a database and a cache, and the part that bites is startup order: the app boots faster than PostgreSQL does, tries to connect and exits. Healthchecks fix it. This post gives a complete file and the notes that explain each choice. It builds on a small Docker image for Rust in the shipping Rust series.

Docker Compose v2, PostgreSQL 17, Redis 7, Rust 1.90.

The file

compose.yamlYAML
services:
  db:
    image: postgres:17
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: change-me
      POSTGRES_DB: app
    volumes:
      - pgdata:/var/lib/postgresql/data
    ports:
      - "127.0.0.1:5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d app"]
      interval: 3s
      timeout: 3s
      retries: 10

  cache:
    image: redis:7
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 3s
      timeout: 3s
      retries: 10

  app:
    build: .
    environment:
      DATABASE_URL: postgres://app:change-me@db:5432/app
      REDIS_URL: redis://cache:6379
      RUST_LOG: info
    ports:
      - "3000:3000"
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_healthy

volumes:
  pgdata:

Run it:

Shell
docker compose up --build

Compose builds the image from the Dockerfile in the current directory, starts db and cache, waits until both report healthy, and then starts app. The password is a placeholder for local development, not something to reuse.

Why these choices

  • **Hostnames db and cache.** Compose creates a network where service names resolve. localhost inside the app container is the container itself.
  • Healthchecks. pg_isready returns success when the server accepts connections. The official Postgres image starts a temporary server to run init scripts, and then restarts, so a plain port check can succeed too early; pg_isready after the final start is reliable enough in practice, but have the app retry anyway.
  • **127.0.0.1:5432:5432.** Publishes the database to the host only on loopback, so psql works from your machine and the network cannot reach it.
  • **Named volume pgdata.** Survives docker compose down. down -v removes it, which is how you reset to a clean database.

The app should retry

Even with healthchecks, a connection can fail during a restart. A short retry loop on the first pool connection makes the service resilient in every environment, including Kubernetes, which has no depends_on:

rust
let pool = loop {
    match sqlx::PgPool::connect(&url).await {
        Ok(p) => break p,
        Err(e) => {
            tracing::warn!("database not ready: {e}");
            tokio::time::sleep(std::time::Duration::from_secs(1)).await;
        }
    }
};

Add a limit so a misconfigured URL fails instead of looping forever.

Migrations

Run them from the app at startup, or as a one-shot service that depends on db and exits, see SQLx migrations. Run sqlx migrate run from the host against the published port during development.

Common mistakes

  1. localhost in DATABASE_URL inside the container
  2. Forgetting down -v and wondering why old data persists
  3. Publishing 5432 on all interfaces on a shared network
  4. latest tags: pin the major versions, as above
  5. Putting real secrets in the file; use an .env file ignored by Git, see git ignore for Rust projects

Limits

Compose suits development and single host setups. It does not give rolling updates or multi-host scheduling. Healthchecks in your own image need curl or a built-in subcommand; see health, readiness and liveness. The file format is documented in the Compose specification.

Also inDatabases
Taggedcompose
Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.