Docker Compose Tutorial: Run Node.js, PostgreSQL and Redis Together

If you have ever followed a project’s README that says “install Node, then install PostgreSQL, then install Redis, then set ten environment variables”, you know how painful local setup can be. This Docker Compose tutorial fixes that. You will write one small file, run one command, and get a working Node.js API talking to a PostgreSQL database and a Redis cache — on any laptop, Windows, macOS or Linux.

What is Docker Compose? (Docker Compose tutorial basics)

Docker runs one container at a time — a small, isolated box that has your app and everything it needs. Real apps usually need more than one box: an API, a database, maybe a cache or a queue. Starting each one with a long docker run ... command, creating networks by hand and remembering the right order gets old quickly.

Docker Compose is the tool that solves this. You write a YAML file that lists your services (containers), how they are built or which image they use, which ports they open, which environment variables they need, and which data should be saved. Then a single command starts the whole stack. Think of it as a recipe card for your whole app.

Before you start

You need two things:

• Docker Desktop (Windows/macOS) or Docker Engine with the Compose plugin (Linux). Docker Desktop already includes Compose.
• A terminal and a code editor like VS Code.

Check that both Docker and Compose are installed:

docker --version
docker compose version

Project structure

We will build a tiny “visit counter” API. Every time you open it, it saves a row in PostgreSQL and increases a counter in Redis. Simple, but it touches every important Compose feature. Create this folder layout:

my-app/
├── compose.yaml
├── .env
└── api/
    ├── Dockerfile
    ├── .dockerignore
    ├── package.json
    └── src/
        └── index.js

Step 1: The Node.js API

First, the package.json. We use ES modules ("type": "module"), Express 5, the pg driver for PostgreSQL and the official redis client.

{
  "name": "visit-counter-api",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "node src/index.js",
    "dev": "node --watch src/index.js"
  },
  "dependencies": {
    "express": "^5.1.0",
    "pg": "^8.13.0",
    "redis": "^5.0.0"
  }
}

Now the API itself. Notice that it does not hard-code any hostnames or passwords. It reads DATABASE_URL and REDIS_URL from environment variables, which Compose will provide.

import express from 'express';
import pg from 'pg';
import { createClient } from 'redis';

const app = express();

// PostgreSQL connection pool (host comes from DATABASE_URL)
const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });

// Redis client (host comes from REDIS_URL)
const cache = createClient({ url: process.env.REDIS_URL });
cache.on('error', (err) => console.error('Redis error:', err.message));
await cache.connect();

// Create the table once, if it does not exist yet
await pool.query(`
  CREATE TABLE IF NOT EXISTS visits (
    id SERIAL PRIMARY KEY,
    visited_at TIMESTAMPTZ NOT NULL DEFAULT now()
  )
`);

app.get('/', async (req, res) => {
  await pool.query('INSERT INTO visits DEFAULT VALUES');
  const { rows } = await pool.query('SELECT COUNT(*)::int AS total FROM visits');
  const hits = await cache.incr('hits');

  res.json({
    message: 'Hello from Docker Compose!',
    totalVisits: rows[0].total, // stored in PostgreSQL
    cacheHits: hits             // stored in Redis
  });
});

app.get('/health', (req, res) => res.json({ status: 'ok' }));

const port = process.env.PORT || 3000;
app.listen(port, () => console.log(`API running on port ${port}`));

Step 2: The Dockerfile

The Dockerfile tells Docker how to build an image for our API. We use the official node:24-alpine image (Node.js 24 is an LTS release, and Alpine keeps the image small).

FROM node:24-alpine

WORKDIR /app

# Copy only package files first, so "npm install" is cached
COPY package*.json ./
RUN npm install --omit=dev

# Now copy the rest of the source code
COPY . .

EXPOSE 3000
CMD ["npm", "start"]

And a .dockerignore so your local node_modules and secrets never get copied into the image:

node_modules
npm-debug.log
.env

Step 3: The compose.yaml file

This is the heart of the Docker Compose tutorial. First, put your settings in a .env file next to compose.yaml. Compose reads this file automatically and replaces ${VARIABLE} placeholders with these values.

POSTGRES_USER=devdojo
POSTGRES_PASSWORD=change-me-please
POSTGRES_DB=appdb

Now the main file:

services:
  api:
    build: ./api
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}
      REDIS_URL: redis://cache:6379
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_healthy
    restart: unless-stopped

  db:
    image: postgres:18-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - db-data:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 3s
      retries: 10
      start_period: 10s

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

volumes:
  db-data:

What each part means

Step 4: Run and test it

From the my-app folder, build and start everything in the background:

docker compose up -d --build

Check that all three services are running and healthy:

docker compose ps

You should see db and cache marked healthy and api marked Up. Now call the API (or open it in your browser):

curl http://localhost:3000
# {"message":"Hello from Docker Compose!","totalVisits":1,"cacheHits":1}

curl http://localhost:3000
# {"message":"Hello from Docker Compose!","totalVisits":2,"cacheHits":2}

Let’s peek inside the database and the cache directly, using docker compose exec to run commands inside running containers:

# Count rows in PostgreSQL
docker compose exec db psql -U devdojo -d appdb -c "SELECT COUNT(*) FROM visits;"

# Read the counter from Redis
docker compose exec cache redis-cli GET hits

Now stop everything and start it again:

docker compose down
docker compose up -d
curl http://localhost:3000

The totalVisits number keeps growing, because PostgreSQL data lives in the db-data volume. The Redis counter, however, starts over — we did not give Redis a volume. That is fine for a cache, and it is a good way to see the difference volumes make.

Step 5: Live reload with Compose Watch

Right now, if you edit index.js you must run docker compose up -d --build again. Compose Watch automates this: it watches files on your computer and updates the container for you. You add a develop.watch section to the service and pick an action. Click the tabs below to compare the three main actions:

  api:
    build: ./api
    command: npm run dev   # runs "node --watch"
    develop:
      watch:
        - action: sync
          path: ./api/src
          target: /app/src

  api:
    build: ./api
    develop:
      watch:
        - action: sync+restart
          path: ./api/src
          target: /app/src

  api:
    build: ./api
    develop:
      watch:
        - action: rebuild
          path: ./api/package.json

In practice you combine them. Here is the api service with the recommended setup — sync source code, rebuild when dependencies change:

  api:
    build: ./api
    command: npm run dev
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}
      REDIS_URL: redis://cache:6379
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_healthy
    develop:
      watch:
        - action: sync
          path: ./api/src
          target: /app/src
        - action: rebuild
          path: ./api/package.json

Start it with watch mode turned on:

docker compose up --watch
# or, to only see watch events:
docker compose watch

Change the message text in index.js, save, and refresh localhost:3000. You will see the new message within a second or two — no rebuild needed. Read more in the official Compose Watch docs.

Everyday Docker Compose commands

You will use these commands almost every day. Bookmark this table:

Common errors and fixes

These are the problems beginners (and plenty of seniors) hit most often:

Best practices

1. Name the file compose.yaml. It is the preferred name today. docker-compose.yml still works.
2. Pin major versions of images (postgres:18-alpine, redis:8-alpine) instead of latest, so a surprise upgrade never breaks your setup.
3. Expose only what you need. Leave out ports for databases unless you want to connect a GUI tool from your computer.
4. Keep secrets out of Git. Use .env locally and a real secret manager in production.
5. Always add health checks for databases, caches and message queues.
6. Use named volumes for data you care about, and remember that down -v deletes them.
7. Use a .dockerignore to keep images small and builds fast.
8. Use profiles for optional tools. Add profiles: ["tools"] to something like pgAdmin, then start it only when needed with docker compose --profile tools up.
9. Run docker compose config when something looks wrong — it shows exactly what Compose sees.

Here is a quick example of an optional database admin tool using a profile:

  pgadmin:
    image: dpage/pgadmin4
    profiles: ["tools"]
    ports:
      - "5050:80"
    environment:
      PGADMIN_DEFAULT_EMAIL: admin@example.com
      PGADMIN_DEFAULT_PASSWORD: admin
    depends_on:
      - db

A normal docker compose up skips it. docker compose --profile tools up -d includes it, and you can open http://localhost:5050 and connect to host db.

FAQ

Conclusion

You now have a real multi-container setup: a Node.js API, a PostgreSQL database with saved data, and a Redis cache — all started with docker compose up. More importantly, you understand the ideas behind it: services talk by name, health checks control start-up order, volumes keep data safe, and Compose Watch gives you fast feedback while coding.

Try extending this project next: add a worker service that reads jobs from Redis, or a frontend service with Vite. The pattern stays exactly the same — one more block in compose.yaml.