Lorixen.
EN

Docker Compose for local development: one command setup

Short answer: Docker Compose lets you describe your app, its database, cache and other services in one compose.yaml file, then start the lot with docker compose up. For a small team, that replaces pages of setup instructions and "works on my machine" problems. Use health checks so the app waits for the database, keep secrets in a local .env that isn't committed, mount or watch your source code for quick changes, and use named volumes so local data survives restarts.

The problem Compose solves

A typical business app needs more than its own code to run locally: a database, maybe Redis for caching or queues, a mail catcher for testing emails, and sometimes a search engine. Without Compose, every developer installs each one by hand, often at different versions, and the setup document is out of date by the second new starter.

With Compose, the whole stack is described in a file in the repository. A new developer clones the code, copies an example environment file and runs one command.

A minimal file for a web app and database

Here's an illustrative compose.yaml for a web app with PostgreSQL and Redis:

services:
  web:
    build: .
    ports:
      - "3000:3000"
    env_file: .env
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
  db:
    image: postgres:18
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: app
    volumes:
      - db-data:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d app"]
      interval: 10s
      retries: 5
  redis:
    image: redis
volumes:
  db-data:

Use the image versions your production environment runs; the ones above are placeholders. The volume path should match what your chosen database image documents.

Make the app wait for the database properly

A common frustration: the app starts before the database is ready, fails to connect and exits. Docker's documentation on startup order explains that Compose always starts containers in dependency order, but by default "started" only means the container is running, not that the service inside is ready.

The fix is the condition setting under depends_on. Docker documents three options: service_started, service_healthy, which waits until the dependency's healthcheck reports healthy, and service_completed_successfully, which waits for a one-off task to finish. Docker's own example uses pg_isready as the health check for PostgreSQL, as in the file above.

service_completed_successfully is handy for a migration or seed container: run it once, then start the web app only if it succeeded.

Handle configuration and secrets locally

Compose can read variables from your shell or from a .env file in the project directory, and a service can load a file with the env_file attribute, according to Docker's environment-variable documentation. A workable pattern:

  • Commit a .env.example with every variable name and safe local defaults.
  • Each developer copies it to .env, which is listed in .gitignore.
  • Never put production credentials in either file.

Local database passwords like app are fine because the database only runs on the developer's machine. Don't publish its port to the outside world on a shared network.

Fast feedback when code changes

Rebuilding an image for every code change is slow. Two common approaches:

  • Bind-mount the source into the container, and let your framework's own reloader pick up changes.
  • Compose Watch, configured under a service's develop section, which can sync changed files into the running container or trigger a rebuild when files like the dependency manifest change. Check Docker's Compose Watch documentation for the current options.

Bind mounts are simpler. Watch tends to behave better on some operating systems where file-change events don't pass cleanly into containers.

Keep data, and know how to reset it

Named volumes, like db-data above, keep your local database between restarts. That's usually what you want, but you'll sometimes need a clean slate. docker compose down stops and removes the containers and keeps named volumes; adding -v removes the volumes too. Make sure everyone knows which is which before someone deletes a week of local test data.

Pair this with a seed script so a fresh database is useful within a minute.

Useful extras for business apps

Compose makes it easy to add tools that help day to day:

  • A mail catcher service that receives every email the app sends locally, so nobody accidentally emails a real customer.
  • A database admin UI on a local port, for inspecting data.
  • Profiles, which let you keep optional services, such as a search engine, in the file but only start them when needed.

Add them gradually. A Compose file that starts twelve services nobody uses is slow and confusing.

Common mistakes

  • Pinning nothing. image: postgres with no version means different developers run different major versions.
  • Assuming production parity. Compose is great for development; it's not a replacement for your production platform's configuration.
  • Committing .env. Even local secrets can include real API keys for third-party sandboxes.
  • Forgetting the README. Write the three commands a new starter needs, and keep them right.

A worked example

Take a hypothetical Seattle cleaning-services company with a booking app maintained by three developers. Each had installed PostgreSQL differently, and one had a much older version. The team added a Compose file with pinned PostgreSQL and Redis versions, a health check, a migration service using service_completed_successfully, a mail catcher and a seed script. Their next contractor had the app running in an afternoon instead of the two days it took the previous one.

FAQ

Do I need Docker Desktop to use Compose?

Not necessarily. Compose runs with Docker Engine on Linux, and there are several ways to run it on Mac and Windows. Check current licensing terms for your organisation's size.

Can we use the same Compose file in production?

Some small apps do, on a single server. For anything bigger, production usually needs separate configuration for scaling, secrets and backups.

Is docker-compose the same as docker compose?

The older standalone tool used the hyphenated name. Current versions are a Docker plugin used as docker compose.

If setting up your app locally takes longer than it should, send us your setup notes and we'll suggest a Compose file.

Sources

WhatsAppBook a call