Run and Safely Update a Docker Swarm Service

You will create a small replicated service, check its tasks, change its image or scale, inspect the result, and remove it cleanly when finished. The commands target Docker 29.8.1 and the docker service command family. Allow about 15 minutes, plus time for your image to download.

Before you start

docker service is a Swarm cluster-management command. Run it on a Swarm 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}}'

For a usable manager, the second command should report active true. If it reports inactive false, stop here and use the correct Docker context or manager. Do not initialise a new Swarm on a shared host just to make an example work: that changes cluster membership and needs an explicit operational decision.

The Docker socket is privileged. Use your normal account if it already has permission, or prefix commands with sudo when your site requires it. The examples below create and remove a service, so do not run them against a name already used by someone else.

Checkpoint 1: create a named service

Creating a service changes cluster state. This example 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 production deployments should pin a reviewed image tag or digest.

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

Expect a row named demo-web with REPLICAS eventually reaching 2/2. A lower count is not automatically a CLI failure. It means tasks are still starting or cannot be scheduled.

Checkpoint 2: find the task-level failure

Services describe the desired state; tasks show what the scheduler actually did. List the tasks without truncated IDs:

docker service ps --no-trunc demo-web

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

For the service definition rather than its task history, use human-readable inspection:

docker service inspect --pretty demo-web

Use machine-readable output when you need to capture exact configuration for a change review:

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

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

Checkpoint 3: change one service property

Scaling a replicated service changes how many tasks the scheduler should maintain. It does not update 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 is a reversible way to stop task placement temporarily, 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. Replace the example tag with the version you have tested:

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

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

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

For a deliberately controlled rollout, configure update settings when creating or updating a service, such as --update-parallelism, --update-delay and --update-failure-action. Verify each option with the installed command's --help output before copying a policy between Docker versions.

Checkpoint 4: read logs and recover

Service logs combine output from 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. Add --no-trunc when the task name or message is needed for diagnosis.

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

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

Rollback is not a substitute for testing. It is also state-changing and may restart tasks. If the service is still unstable, preserve the task error and service inspection output before making another change. Avoid repeatedly updating and rolling back, which can obscure which configuration is running.

Checkpoint 5: remove the example

Removal is destructive to this service's tasks. It does not delete the image from a registry, but it does remove the Swarm service and its task records. Confirm the name, then run:

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

The second command should return no matching service. There is no undo command for a removed service. Recreate it from the original command, or from the version-controlled deployment definition used by your team.

Common traps

• Running on a worker: the command needs a manager. A correct client installation is not enough.
• Reading only docker service ls: a 1/2 replica count needs docker service ps to expose the task error.
• Expecting scaling to refresh an image: use service update --image for an image change.
• Using latest in production: review and pin the image version or digest so a later update is intentional.
• Confusing published and target ports: published is the port clients reach on the swarm; target is the port inside the service container.