Scaling services with replicas in Docker - Commands & Configuration

Introduction

Sometimes one copy of a service is not enough to handle all the users or tasks. Scaling with replicas means running multiple copies of the same service to share the work and keep things running smoothly.

When your website gets more visitors and one server copy is too slow

When you want to keep your app running even if one copy crashes

When you need to handle many tasks at the same time without delays

When you want to update your app without stopping all users

When you want to balance the work evenly across several servers

Config File - docker-compose.yml

docker-compose.yml

version: '3.8'
services:
  webapp:
    image: nginx:1.23
    deploy:
      replicas: 3
    ports:
      - "8080:80"

This file tells Docker Compose to run the nginx web server with 3 copies (replicas).

The deploy.replicas key sets how many copies to run.

The ports section maps port 8080 on your computer to port 80 inside each container.

Commands

This command starts Docker Swarm mode on your machine, which is needed to manage multiple replicas of a service.

Terminal

docker swarm init

Expected Output

Swarm initialized: current node (abcdef123456) is now a manager.



To add a worker to this swarm, run the following command:

    docker swarm join --token SWMTKN-1-0abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890 192.168.1.2:2377



To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.

This command deploys the stack named 'myapp' using the docker-compose.yml file, creating 3 replicas of the webapp service.

Terminal

docker stack deploy -c docker-compose.yml myapp

Expected Output

Creating network myapp_default

Creating service myapp_webapp

→

-c - Specifies the compose file to use

This command lists all running services and shows how many replicas are running for each.

Terminal

docker service ls

Expected Output

ID                  NAME                MODE                REPLICAS            IMAGE               PORTS

abcdef123456        myapp_webapp        replicated          3/3                 nginx:1.23          *:8080->80/tcp

This command shows detailed information about each replica of the webapp service, including their current state and node.

Terminal

docker service ps myapp_webapp

Expected Output

ID                  NAME                IMAGE               NODE                DESIRED STATE       CURRENT STATE           ERROR               PORTS

123abc456def        myapp_webapp.1      nginx:1.23          node1               Running             Running 2 minutes ago                       

789def123abc        myapp_webapp.2      nginx:1.23          node1               Running             Running 2 minutes ago                       

456def789abc        myapp_webapp.3      nginx:1.23          node1               Running             Running 2 minutes ago                       

Key Concept

If you remember nothing else from this pattern, remember: running multiple replicas of a service shares the work and improves reliability.

Common Mistakes

Trying to scale replicas without initializing Docker Swarm mode

Docker needs Swarm mode active to manage multiple replicas; without it, scaling commands fail.

Run 'docker swarm init' first to enable Swarm mode before deploying services with replicas.

Using 'docker-compose up' instead of 'docker stack deploy' for scaling replicas

'docker-compose up' does not support swarm mode scaling; replicas won't be created.

Use 'docker stack deploy -c docker-compose.yml <stack_name>' to deploy and scale services with replicas.

Not exposing ports correctly when running multiple replicas

If ports are not mapped properly, you cannot access the service from outside the Docker network.

Map ports in the compose file under 'ports' so the service is reachable on your machine.

Summary

Initialize Docker Swarm mode to enable service scaling with replicas.

Use a docker-compose.yml file with the 'deploy.replicas' key to define how many copies to run.

Deploy the stack with 'docker stack deploy' and verify replicas with 'docker service ls' and 'docker service ps'.