Run Postgres, Redis and MinIO locally with Docker Compose
Installing Postgres on your laptop works until the second project, which wants a different version, or until you wipe the machine and cannot remember what you configured. Docker Compose replaces that with one file you can read, delete and recreate, and which every person on the project runs identically.
This explains a working compose file line by line: Postgres for data, Redis for cache and queues, MinIO as a local stand-in for S3, and Mailhog so you can see your application's email without sending any.
16 min read. Commands and output last run against Grit v3.560.0.
What you will have at the end
Four services running locally with one command, and gone again with another, leaving nothing installed on your machine.
Data that survives restarts, because the volumes are named rather than anonymous, and an understanding of why that distinction is the one that loses people's databases.
Ports chosen so they do not fight whatever you already have installed.
What a container actually is
Not a virtual machine. A container is a normal process on your kernel, with its own view of the filesystem, the network and the process list. That is why it starts in a second rather than a minute, and why a Postgres container uses roughly the memory Postgres uses.
Three words you need, and they are the ones people conflate.
- An image is a read-only template: Postgres 16, built and published by somebody. You never change an image.
- A container is a running instance of an image. Delete it and you lose everything it wrote, unless that something was written to a volume.
- A volume is storage that outlives the container. This is where your database actually lives.
Compose is a file that describes several containers and how they are wired together, so that docker compose up starts the lot in the right order.
01Install Docker
macOS and Windows: Docker Desktop from docker.com. It is an application, and it must be open for any docker command to work.
Windows specifically: enable WSL2 when the installer offers it. The alternative, Hyper-V, is slower and has more edge cases. If the installer complains that virtualisation is disabled, it is a BIOS setting rather than anything in Windows.
Linux: install Docker Engine from your distribution's instructions, not the docker.io package, which is usually behind. Then add yourself to the docker group so you are not typing sudo all day:
$sudo usermod -aG docker $USER$newgrp docker
Checkpoint. docker run --rm hello-world prints a greeting and exits. If it does, everything below will work.
02Write the compose file
One file at the root of your project. Read the comments: every one of them is a decision somebody made after being bitten.
services:postgres:image: postgres:16-alpinerestart: unless-stoppedports:# Host 5434, not the Postgres default 5432. Two collisions this avoids:# a Postgres installed on the host, and Windows reserving 5432 inside# its dynamic Hyper-V port range. The container still listens on 5432# inside the Docker network, which is what other containers use.- "127.0.0.1:${POSTGRES_PORT:-5434}:5432"environment:# :- supplies a fallback, so the file still works with no .envPOSTGRES_USER: ${POSTGRES_USER:-app}POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-app}POSTGRES_DB: ${POSTGRES_DB:-app}volumes:- postgres-data:/var/lib/postgresql/datahealthcheck:test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-app}"]interval: 5stimeout: 5sretries: 5redis:image: redis:7-alpinerestart: unless-stoppedports:# Host 6380, because a native Redis or Memurai install takes 6379.- "127.0.0.1:${REDIS_PORT:-6380}:6379"volumes:- redis-data:/datahealthcheck:test: ["CMD", "redis-cli", "ping"]interval: 5stimeout: 5sretries: 5minio:image: minio/miniorestart: unless-stoppedports:# Host 9002 and 9003. Portainer and several monitoring stacks take# 9000 and 9001.- "127.0.0.1:9002:9000"- "127.0.0.1:9003:9001"environment:# :? refuses to start with a clear message rather than booting with a# default password, which is the right behaviour for a credential.MINIO_ROOT_USER: ${MINIO_ACCESS_KEY:?set MINIO_ACCESS_KEY in .env}MINIO_ROOT_PASSWORD: ${MINIO_SECRET_KEY:?set MINIO_SECRET_KEY in .env}volumes:- minio-data:/datacommand: server /data --console-address ":9001"mailhog:image: mailhog/mailhogrestart: unless-stoppedports:- "127.0.0.1:1025:1025" # SMTP, what your app connects to- "127.0.0.1:8025:8025" # the web inbox you readvolumes:postgres-data:redis-data:minio-data:
And the credentials beside it, which is the file you never commit:
POSTGRES_USER=appPOSTGRES_PASSWORD=choose-somethingPOSTGRES_DB=appPOSTGRES_PORT=5434REDIS_PORT=6380MINIO_ACCESS_KEY=local-dev-keyMINIO_SECRET_KEY=local-dev-secret
Add .env to .gitignore before the first commit
Once a credential is in git history, removing it from the current file does nothing: the old commit still has it, and on a public repository it is scraped within minutes. Getting it out afterwards means rewriting history for everybody.
03Start it, and check it
$docker compose up -d # -d detaches, so you get your terminal back$docker compose ps # what is running, and whether it is healthy
Checkpoint. docker compose ps lists four services, and Postgres and Redis say healthy rather than just running. If Postgres says starting for more than ten seconds, read its logs:
$docker compose logs -f postgres # -f follows; Ctrl-C stops following,# not the container
Then prove you can actually talk to each one:
# Postgres: a shell inside the container$docker compose exec postgres psql -U app -d app -c '\l'# Redis$docker compose exec redis redis-cli ping # PONG# MinIO console, in a browser$open http://localhost:9003 # xdg-open on Linux, start on Windows# Mailhog inbox$open http://localhost:8025
The four lines that matter most
127.0.0.1:5434:5432
Three parts: bind address, host port, container port. Writing 5434:5432 without the address binds to every interface, which means your database is reachable by anyone on the coffee shop wifi, with the password you chose while in a hurry. The 127.0.0.1 prefix costs nothing and closes that.
Containers do not need this at all to reach each other. Inside the Docker network they use the service name and the real port: postgres:5432. The ports line exists only so that programs on your machine, your API running outside Docker, a database GUI, can get in.
postgres-data:/var/lib/postgresql/data
A named volume. The name on the left is declared in the volumes: block at the bottom, and it is what makes the data survive docker compose down and come back on the next up.
Omit the name and you get an anonymous volume, which survives too, but under a random identifier that nothing reconnects to. That is how people conclude Docker loses their data: it did not, they just cannot find it.
healthcheck
A container being up does not mean the service inside it is ready. Postgres spends a few seconds initialising on first run, and an API that connects during that window fails with connection refused and dies. The healthcheck is what lets other services wait for ready rather than started:
api:depends_on:postgres:condition: service_healthy
depends_on on its own, without the condition, waits only for the container to exist, which is almost never what you wanted.
${POSTGRES_PASSWORD:-app} against ${MINIO_SECRET_KEY:?set it}
The first supplies a default. The second refuses to start, with your message, when the variable is missing. Use the second for anything that is a credential in production: a default password is a password somebody will still be using in a year.
The six commands you will actually use
$docker compose up -d # start everything$docker compose ps # what is running and how healthy$docker compose logs -f api # follow one service's output$docker compose restart redis # restart one service$docker compose down # stop and remove containers, KEEP volumes$docker compose down -v # ... and delete the volumes too
down against down -v
down is safe and routine: it stops everything and leaves your data. down -v deletes the volumes, which means the database. It is the right command when you want a genuinely fresh start, and the wrong one by accident. There is no confirmation prompt.
When it goes wrong
Bind for 0.0.0.0:5432 failed: port is already allocated
Something else holds the port. Usually a Postgres installed natively, or another project's compose stack still up.
$docker ps --format "table {{.Names}}\t{{.Ports}}"
Change only the host side of the mapping, the left-hand number, and update the matching variable in .env. Changing one without the other is the next error you will see.
Cannot connect to the Docker daemon. Is the docker daemon running?
Docker Desktop is not open, or on Linux the service is not started. The message never says so plainly, which is why it is the most reported Docker error there is.
dial tcp 127.0.0.1:5432: connect: connection refused (from inside a container)
Inside a container, 127.0.0.1 means that container, not your machine. A service looking for the database at localhost is looking at itself.
Use the service name: the connection string becomes postgres://app:app@postgres:5432/app. And note the port is the container port 5432, not the host port 5434, because this connection never leaves the Docker network.
role "app" does not exist / database "app" does not exist
The Postgres image creates the user and database from the environment variables only on the very first start, when the data directory is empty. If you started the container once with different credentials, the volume already holds a database that does not know about your new ones, and changing the compose file does nothing.
$docker compose down -v # deletes the volume, so the next start initialises$docker compose up -d
That deletes the data in it. On a local development database that is usually fine.
no space left on device
Images and build caches accumulate. docker system df shows where it went and docker system prune reclaims the safe parts. Leave --volumes off unless you mean to delete databases.
Everything is extremely slow on Windows or macOS
Almost always a bind mount crossing the boundary between the host filesystem and the container. On Windows, keep the project inside the WSL2 filesystem, under ~, rather than under /mnt/c. On macOS, enable VirtioFS in Docker Desktop's settings if it is not already on.
This does not apply to the file above, which uses named volumes rather than bind mounts. It bites when you start mounting your source code into a container.
The same file, written for you
A Grit project ships this compose file already, with the ports chosen as above, the healthchecks wired, and the application's environment variables pointing at the right service names.
$grit new myapp$cd myapp$docker compose up -d$grit migrate$grit start
The generated file has one difference worth knowing about: nothing in the production compose file publishes a port at all. Databases are reachable only from inside the Docker network, and you reach them over an SSH tunnel. Development is the only place a database port is on your machine, which is the right way round.
Frequently asked questions
- Do I need Docker to develop locally?
- No. You can install Postgres and Redis natively, and for a single project that is perfectly workable. Docker earns its place at the second project, at the first version conflict, and on the first day somebody new joins and has to reproduce your setup from a README.
- Will docker compose down delete my database?
- Not with named volumes, which is what the file above uses:
downremoves the containers and leaves the data, and the nextupfinds it again.down -vdoes delete it, deliberately and without asking. - Why does my API say connection refused when the database is clearly running?
- Two likely causes. If the API runs inside Docker, it must use the service name and container port (
postgres:5432), because127.0.0.1inside a container means that container. If the API runs on your machine, it uses the host port (localhost:5434). Mixing the two up is the single most common Compose mistake. - Is MinIO good enough to stand in for S3?
- For development, yes: it speaks the S3 API, so the same SDK and the same code work against both, and you change an endpoint and some credentials to move to the real thing. The differences that matter appear at scale and around IAM policies, neither of which you are exercising locally.
Next steps
- Fix the errors you hit starting outThe exact messages, with the cause and the fix per operating system.
- Build your first full-stack appA Go API and a React frontend, with a checkpoint at every step.
- Docker in a Grit projectThe generated development and production stacks, and what differs between them.
- DeployingWhat changes between the compose file you run locally and the one on a server.
