Run and Safely Update a Docker Swarm Service

A container you started by hand does not come back after a crash; a Docker Swarm service does, which is the whole point of docker service. This walks through creating a small replicated service, checking its tasks, changing its image or scale, inspecting the result, and removing it cleanly when you are finished. Docker 29.8.1, about 15 minutes plus however long your image takes to pull.

Before you start

docker service is a Swarm cluster-management command. Run it on a manager, not an ordinary worker. Check both the client version and the node's role first:

docker --version
docker info --format '{{.Swarm.LocalNodeState}} {{.Swarm.ControlAvailable}}'

A usable manager reports active true on the second command. If it reports inactive false, stop and use the correct context or manager instead. Do not initialise a new Swarm on a shared host just to make an example work: that changes cluster membership and needs its own decision, not a shortcut here.

The Docker socket is privileged. Use your normal account if it already has permission, or prefix commands with sudo only when your site requires it. The examples below create and remove a service, so pick a name nobody else is using.

1. Create a named service

Creating a service changes cluster state. This starts two Nginx tasks and publishes container port 80 on port 8080 through Swarm's routing mesh. The latest tag keeps the example portable, but a production deployment should pin a reviewed tag or digest instead:

docker service create   --name demo-web   --replicas 2   --publish published=8080,target=80   nginx:latest

Without --detach, the client waits for the service to converge. A successful response prints a service ID. Confirm the desired state and current replica count:

docker service ls --filter name=demo-web

2. Find the task-level failure

A service describes the desired state; its tasks show what the scheduler actually did. List them without truncated IDs:

docker service ps --no-trunc demo-web

Look at CURRENT STATE and ERROR. A task stuck in Pending or repeatedly restarting is usually an unavailable image, a node lacking the required resources, or a placement constraint no node satisfies. This command is read-only and is the first useful check after a surprising replica count.

For the service definition itself, use the human-readable form:

docker service inspect --pretty demo-web

For an exact configuration to paste into a change review, use the machine-readable one:

docker service inspect --format '{{json .Spec.TaskTemplate.ContainerSpec.Image}}' demo-web

The image shown may include a content digest. Swarm only resolves a tag when the service is created or explicitly updated; scaling the replica count does not silently fetch a newer image.

3. Change one service property

Scaling changes how many tasks the scheduler maintains. It does not touch the image:

docker service scale demo-web=3
docker service ls --filter name=demo-web

Wait for 3/3 before moving on. Scaling to zero reversibly stops task placement, but it is still an operational change; restore the previous value with docker service scale demo-web=2.

To deploy a new image, use docker service update and state the image explicitly, with the version you have actually tested:

docker service update   --image nginx:latest   demo-web

Docker replaces tasks according to the service's update policy. Watch the rollout instead of assuming a returned service ID means every task is healthy:

docker service ps demo-web
docker service ls --filter name=demo-web

4. Read logs and recover from a bad update

Service logs combine output from all its tasks. Start with a bounded tail so a noisy application does not fill your terminal:

docker service logs --tail 50 --timestamps demo-web

Use --follow only when you intend to keep a terminal attached, and add --no-trunc when you need the full task name or message for diagnosis.

If an update is bad, identify the failing rollout with docker service ps demo-web first. A rollback returns the service to its configuration from before the most recent update:

docker service rollback demo-web
docker service ps demo-web

5. Remove the example

docker service rm demo-web
docker service ls --filter name=demo-web

The second command should return no matching service. Recreate it from the original command, or better, from the version-controlled deployment definition your team actually uses.

Common traps

• Running on a worker. The command needs a manager; a correct client install is not enough.
• Reading only docker service ls. A 1/2 replica count needs docker service ps to expose the task error underneath it.
• Expecting scaling to refresh an image. Use service update --image for that instead.
• Using latest in production. Pin the image version or digest so a later update is a decision, not an accident.
• Confusing published and target ports. published is what clients reach on the swarm; target is the port inside the service container.