---
obj: concept
source: https://docs.docker.com/engine/swarm
---

# Docker Swarm
Docker Swarm is a native clustering and orchestration solution for [Docker](Docker.md). It enables the creation and management of a swarm of Docker nodes, turning them into a single, virtual [Docker](Docker.md) host. Docker Swarm allows you to deploy and manage containerized applications across a cluster of machines, providing high availability, scalability, and ease of use.

## Getting started

1. Initialize a Swarm on a manager node:

```bash
docker swarm init
```

2. Join additional nodes to the Swarm:
```bash
docker swarm join --token <token> <manager-ip>
```

3. Deploy a service
Here's an example [Docker Compose](Docker%20Compose.md) file for a simple web service:
```yml
version: '3'

services:
  web:
    image: nginx
    ports:
      - "80:80"
    deploy:
      replicas: 3
```

Deploy this service using:
```bash
docker stack deploy -c docker-compose.yml myapp
```

## `docker swarm`
Manage Swarm

### `docker swarm ca`
Display and rotate the root CA
Usage:
```sh
# Display Cert
docker swarm ca

# Rotate cert
docker swarm ca --rotate
```

### `docker swarm init`
Initialize a swarm
Usage: `docker swarm init --advertise-addr IP`

### `docker swarm join-token`
Manage join tokens
Usage: `docker swarm join-token [--rotate] (worker|manager)`

### `docker swarm join`
Join a swarm as a node and/or manager
Usage: `docker swarm join [--token token] HOST:PORT`

### `docker swarm leave`
Leave the swarm
Usage: `docker swarm leave [-f, --force]`

## `docker node`
Manage Swarm nodes

### `docker node demote`
Demote one or more nodes from manager in the swarm
Usage: `docker node demote NODE [NODE...]`

### `docker node ls`
List nodes in the swarm
Usage: `docker node ls [--format json] [-f, --filter FILTER=VALUE]`

The currently supported filters are:
- `id`
- `label`
- `node.label`
- `membership`
- `name`
- `role`

### `docker node promote`
Promote one or more nodes to manager in the swarm
Usage: `docker node promote NODE [NODE...]`

### `docker node ps`
List tasks running on one or more nodes, defaults to current node
Usage: `docker node ps [--format json] [NODE...]`

### `docker node rm`
Remove one or more nodes from the swarm
Usage: `docker node rm [-f, --force] NODE [NODE...]`

### `docker node update`
Update metadata about a node, such as its availability, labels, or roles.
Usage: `docker node update [OPTIONS] NODE`

#### Options

| Option                  | Description                                           |
| ----------------------- | ----------------------------------------------------- |
| `--availability state`  | Availability of the node (`active`, `pause`, `drain`) |
| `--label-add	key=value` | Add or update a node label                            |
| `--label-rm key`        | Remove a node label if exists                         |
| `--role role`           | Role of the node (`worker`, `manager`)                |

## `docker service`
These commands apply to services and are almost identical to container commands.
```shell
docker service create [OPTIONS] IMAGE [COMMAND] [ARG...]
docker service logs [OPTIONS] SERVICE|TASK
docker service ls [OPTIONS]
docker service ps [OPTIONS] SERVICE [SERVICE...]
docker service rm SERVICE [SERVICE...]
docker service scale SERVICE=REPLICAS [SERVICE=REPLICAS...]
```

## `docker stack`
Manage Swarm stacks. This command works on a swarm orchestrator.

### `docker stack deploy`
Deploy a new stack or update an existing stack
Usage: `docker stack deploy [OPTIONS] STACK`

#### Options

| Option                    | Description                                          | 
| ------------------------- | ---------------------------------------------------- |
| `-c, --compose-file file` | Path to a Compose file, or `-` to read from stdin    |
| `--prune`                 | Prune services that are no longer referenced         |
| `--with-registry-auth`    | Send registry authentication details to Swarm agents |

### `docker stack ls`
List stacks
Usage: `docker stack ls [--format json]`

### `docker stack ps`
List the tasks in the stack
Usage: `docker stack ps [--format json]`

### `docker stack rm`
Remove one or more stacks
Usage: `docker stack rm STACK [STACK...]`

### `docker stack services`
List the services in the stack
Usage: `docker stack services [--format json] STACK`
