---
description: How to deploy a stack to a swarm
keywords: guide, swarm mode, composefile, stack, compose, deploy
title: Deploy a stack to a swarm
---

When running Docker Engine in swarm mode, you can use `docker stack deploy` to
deploy a complete application stack to the swarm. The `deploy` command accepts
a stack description in the form of a [Compose file](/reference/compose-file/legacy-versions.md).

{{% include "swarm-compose-compat.md" %}}

To run through this tutorial, you need:

1.  A Docker Engine running in [Swarm mode](swarm-mode.md).
    If you're not familiar with Swarm mode, you might want to read
    [Swarm mode key concepts](key-concepts.md)
    and [How services work](how-swarm-mode-works/services.md).

    > [!NOTE]
    >
    > If you're trying things out on a local development environment,
    > you can put your engine into Swarm mode with `docker swarm init`.
    >
    > If you've already got a multi-node swarm running, keep in mind that all
    > `docker stack` and `docker service` commands must be run from a manager
    > node.

2.  A current version of [Docker Compose](/manuals/compose/install/_index.md).

## Set up a Docker registry

Because a swarm consists of multiple Docker Engines, a registry is required to
distribute images to all of them. You can use the
[Docker Hub](https://hub.docker.com) or maintain your own. Here's how to create
a throwaway registry, which you can discard afterward.

1.  Start the registry as a service on your swarm:

    ```console
    $ docker service create --name registry --publish published=5000,target=5000 registry:2
    ```

2.  Check its status with `docker service ls`:

    ```console
    $ docker service ls

    ID            NAME      REPLICAS  IMAGE                                                                               COMMAND
    l7791tpuwkco  registry  1/1       registry:2@sha256:1152291c7f93a4ea2ddc95e46d142c31e743b6dd70e194af9e6ebe530f782c17
    ```

    Once it reads `1/1` under `REPLICAS`, it's running. If it reads `0/1`, it's
    probably still pulling the image.

3.  Check that it's working with `curl`:

    ```console
    $ curl http://127.0.0.1:5000/v2/

    {}
    ```

## Create the example application

The app used in this guide is based on the hit counter app in the
[Get started with Docker Compose](/manuals/compose/gettingstarted.md) guide. It consists
of a Python app which maintains a counter in a Redis instance and increments the
counter whenever you visit it.

1.  Create a directory for the project:

    ```console
    $ mkdir stackdemo
    $ cd stackdemo
    ```

2.  Create a file called `app.py` in the project directory and paste this in:

    ```python
    from flask import Flask
    from redis import Redis

    app = Flask(__name__)
    redis = Redis(host='redis', port=6379)

    @app.route('/')
    def hello():
        count = redis.incr('hits')
        return 'Hello World! I have been seen {} times.\n'.format(count)

    if __name__ == "__main__":
        app.run(host="0.0.0.0", port=8000, debug=True)
    ```

3.  Create a file called `requirements.txt` and paste these two lines in:

    ```none
    flask
    redis
    ```

4.  Create a file called `Dockerfile` and paste this in:

    ```dockerfile
    # syntax=docker/dockerfile:1
    FROM python:3.4-alpine
    ADD . /code
    WORKDIR /code
    RUN pip install -r requirements.txt
    CMD ["python", "app.py"]
    ```

5.  Create a file called `compose.yaml` and paste this in:

    ```yaml
      services:
        web:
          image: 127.0.0.1:5000/stackdemo
          build: .
          ports:
            - "8000:8000"
        redis:
          image: redis:alpine
    ```

    The image for the web app is built using the Dockerfile defined
    above. It's also tagged with `127.0.0.1:5000` - the address of the registry
    created earlier. This is important when distributing the app to the
    swarm.


## Test the app with Compose

1.  Start the app with `docker compose up`. This builds the web app image,