Demo Example Voting Application with Docker Compose

In this lesson you’ll run the same voting application stack using Docker Compose instead of starting each container manually. Docker Compose lets you define the entire multi-container stack in a single YAML file and bring it up or tear it down with a single command. Below are the manual steps (kept for reference) that mirror what the Compose configuration will do.

Manual steps (reference)

Create a network:

docker network create voting-app

Start Redis and Postgres:

docker run -d --name redis --network voting-app redis:alpine

docker run -d --name db --network voting-app \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -v db-data:/var/lib/postgresql/data \
  postgres:15-alpine

Build the application images locally:

docker build -t vote ./vote
docker build -t result ./result
docker build -t worker ./worker

Run the application containers and publish ports:

docker run -d --name vote --network voting-app -p 8080:80 vote
docker run -d --name result --network voting-app -p 8081:80 result
docker run -d --name worker --network voting-app worker

Confirm images and containers:

docker images
docker ps

Example (condensed) output for images:

$ docker images
REPOSITORY             TAG           IMAGE ID       SIZE
postgres               15-alpine     85c4c0fadf81   270MB
redis                  alpine        8b92846b980b   114MB
result                 latest        8ff63d31e3fa   242MB
vote                   latest        de5e8dc4a5b3   188MB
worker                 latest        193dff5d9409   196MB

If you have images but no running containers, docker ps will show no entries.

Now we’ll convert those manual steps into a Docker Compose file so the entire stack can be started with a single command.

Compose file: reference configuration

Create a Compose file (for example simple.yaml) in your project directory. The first version uses pre-built images (mirrors the manual docker run approach):

# simple.yaml
services:
  vote:
    image: vote
    ports:
      - "8080:80"

  result:
    image: result
    ports:
      - "8081:80"

  worker:
    image: worker

  redis:
    image: redis:alpine

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:

Notes:

vote and result need port mappings to expose their web UIs: 8080:80 and 8081:80.
redis is redis:alpine and does not need a published port for internal service-to-service networking.
The Postgres service defines environment variables and a named volume db-data to persist database data.

Run the stack:

docker compose -f simple.yaml up

What Compose does when you run up:

Creates a default network (project_name_default) unless you define one explicitly.
Creates and starts containers for each service.
If run in attached mode (default), logs for all services stream to your terminal with a service-name prefix.

Example (truncated) startup output:

[+] Running 6/6
✓ Network example-voting-app_default    Created
✓ Container example-voting-app-redis-1  Created
✓ Container example-voting-app-vote-1   Created
✓ Container example-voting-app-db-1     Created
✓ Container example-voting-app-worker-1 Created
✓ Container example-voting-app-result-1 Created
Attaching to db-1, redis-1, result-1, vote-1, worker-1
db-1    | PostgreSQL Database directory appears to contain a database; skipping initialization
redis-1 | 1:M 29 May 2026 00:23:39.815 * Ready to accept connections
vote-1  | [2026-05-29 00:26:45 +0000] [1] [INFO] Starting gunicorn 26.0.0
result-1| App running on port 80
worker-1| Connecting to db
worker-1| Connecting to redis

Open the apps in your browser:

Vote app: http://localhost:8080
Result app: http://localhost:8081

To stop services started in attached mode, press Ctrl+C. To remove the containers, network, and default volumes created by Compose:

docker compose -f simple.yaml down

Docker Compose automatically creates a project network (derived from the directory name) if you don’t explicitly define one. You don’t need to manually create voting-app unless you have a specific reason to reuse a pre-existing network.

Build images with Compose (build from local Dockerfiles)

You don’t need to build images manually before using Compose. Replace image: with build: to instruct Compose to build images from local Dockerfiles. Example:

# simple.yaml (build-based)
services:
  vote:
    build: ./vote
    ports:
      - "8080:80"

  result:
    build: ./result
    ports:
      - "8081:80"

  worker:
    build: ./worker

  redis:
    image: redis:alpine

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:

Run the build-and-up flow:

docker compose -f simple.yaml up

Compose will:

Build the vote, result, and worker images from the specified directories.
Start the entire stack once images are built.

Typical build-and-up logs:

Building vote
Step 1/10 : FROM python:3.11-slim
...
Successfully built <image-id>
Successfully tagged example-voting-app_vote:latest
Creating network "example-voting-app_default" with the default driver
Creating example-voting-app-redis-1    ... done
Creating example-voting-app-db-1       ... done
Creating example-voting-app-vote-1     ... done
Attaching to db-1, redis-1, result-1, vote-1, worker-1
vote-1  | [2026-05-29 00:26:45 +0000] [1] [INFO] Starting gunicorn 26.0.0
result-1| App running on port 80
worker-1| Connecting to db

Stop and clean up:

# Stop and remove containers, networks, and default volumes created by the Compose project
docker compose -f simple.yaml down

If you add -v to docker compose down -v, it will remove named volumes like db-data and delete persisted database data. Use with caution if you need to retain Postgres state between runs.

Quick reference — services, ports, and persistence

Service	Image / Build	Ports exposed	Purpose / Notes
vote	`image: vote` or `build: ./vote`	`8080:80`	Frontend for voting (web UI)
result	`image: result` or `build: ./result`	`8081:80`	Results dashboard (web UI)
worker	`image: worker` or `build: ./worker`	(none)	Background worker that writes votes to DB
redis	`redis:alpine`	(none)	In-memory store for vote queue; internal networking only
db	`postgres:15-alpine`	(none)	Postgres DB; uses named volume `db-data` for persistence

Troubleshooting tips

Duplicate-key DB errors: If you see Postgres duplicate-key errors, it’s usually because the database wasn’t cleaned between runs and a worker retried an insert for an ID that already exists.
Hostname resolution: Compose services resolve each other by service name. If a service cannot reach Redis or Postgres, ensure the hostnames used in your code match the Compose service names (e.g., redis, db).
Follow logs for a specific service:

docker compose logs -f <service>
# Example
docker compose logs -f worker

Rebuild a specific service without restarting others:

docker compose build vote
docker compose up -d vote

Summary

Using Docker Compose:

Simplifies launching multi-container applications with a single YAML definition.
Supports both using pre-built images (image:) and building from local Dockerfiles (build:).
Handles networking, service orchestration, and volume management for you.

Useful links and references:

Docker Compose documentation: https://docs.docker.com/compose/
Docker CLI reference: https://docs.docker.com/engine/reference/commandline/cli/
PostgreSQL Docker image docs: https://hub.docker.com/_/postgres

Introduction

Docker Commands

Docker Images

Docker Compose

Docker Engine, Storage

Docker Networking

Docker Registry

Docker on Mac & Windows

Container Orchestration - Docker Swarm & Kubernetes

Conclusion

Docker Run Commands

Demo Example Voting Application with Docker Compose

Manual steps (reference)

Compose file: reference configuration

Build images with Compose (build from local Dockerfiles)

Quick reference — services, ports, and persistence

Troubleshooting tips

Summary

Watch Video

Practice Lab

​Manual steps (reference)

​Compose file: reference configuration

​Build images with Compose (build from local Dockerfiles)

​Quick reference — services, ports, and persistence

​Troubleshooting tips

​Summary

Watch Video

Practice Lab

Manual steps (reference)

Compose file: reference configuration

Build images with Compose (build from local Dockerfiles)

Quick reference — services, ports, and persistence

Troubleshooting tips

Summary