85

I'm learning about using Docker Compose to deploy applications in multiple containers, across multiple hosts. And I have come across two configuration files - stack file, and Compose file.

From the Cloud stack file YAML reference, it states a stack file is a file in YAML format that defines one or more services, similar to a docker-compose.yml file but with a few extensions.

And from this post, it states that stacks are very similar to docker-compose except they define services while docker-compose defines containers.

They look very similar, so I am wondering when I would use the stack file, and when to use the Compose file?

dayuloli
  • 16,205
  • 16
  • 71
  • 126
  • 1
    Good question. I would also like to ask why we need Docker stack when we have docker compose already? In the second link it states docker stack is a service to docker engine where docker compose is not. Then why cannot we just upgrade docker compose and make it a service? – Dustin Sun Mar 29 '17 at 17:38
  • 1
    @lonelyloner great question, my guess it's because docker-compose is a tool of its own and it is not integrated into docker. On Linux, I had to install it separately, where on Windows I believe it comes together with Docker. Hopefully , in future, docker will merge them, and there will be just stack file. – Roman Mik Mar 29 '17 at 17:52

2 Answers2

80

Conceptually, both files serve the same purpose - deployment and configuration of your containers on docker engines.

Docker-compose tool was created first and its purpose is "for defining and running multi-container Docker applications" on a single docker engine. (see docker compose overview )

You use docker-compose up to create/update your containers, networks, volumes and so on.

Where Docker Stack is used in Docker Swarm (Docker's orchestration and scheduling tool) and, therefore, it has additional configuration parameters (i.e. replicas, deploy, roles) that are not needed on a single docker engine.

The stack file is interpreted by docker stack command. This command can be invoked from a docker swarm manager only.

You can convert docker-compose.yml to docker-cloud.yml and back. However, as stated in your question, you must pay attention to the differences. Also, you need to keep in mind that there're different versions for docker-compose. Presently, the latest version is version 3. (https://docs.docker.com/compose/compose-file/)

Edit: An interesting blog, that might help to understand the differences, can be found here https://blog.nimbleci.com/2016/09/14/docker-stacks-and-why-we-need-them/

Community
  • 1
  • 1
Roman Mik
  • 3,179
  • 3
  • 27
  • 49
  • 1
    Yeah, this confused me because the Compose file also has mention of swarm-related properties, such as [`deploy`](https://docs.docker.com/compose/compose-file/#deploy), which are ignored when you use `docker compose`, and only in effect `docker stack deploy`. I guess, for all intents and purposes, for the 3+ version of compose, they are the same? – dayuloli Mar 30 '17 at 13:02
  • Version 3 is different from 2. Not a lot. Notably the way volumes are declared. There are other changes too. Version 3 compose should be able to work on swarm without change, but in reality you would want to add swarm configurations especially if your containers have volumes and you can't afford the loss of their data on redeployment. – Roman Mik Mar 30 '17 at 13:08
  • 8
    @sudo "docker stack" works on Docker Swarm only . docker-compose is an add-on to dock to help orchestration of services on a single docker engine. Docker stack is a brain-child of docker-compose. hopefully in future, they will merge both together and just keep docker stack – Roman Mik Oct 02 '17 at 19:35
  • 1
    Just to add it as a comment to this answer; Docker Compose can build, pull, and update the images it uses, while Docker Stack can't. You'll also have to convert single-engine/machine docker instances to a swarm before you can use your `docker-compose.yml` file with Docker Stack; some properties may be ignored, but assuming the yaml is using version 3.x; it would work interchangeably. So as a general statement; `docker-compose` is better suited for development, whereas `docker stack` is better suited for deployment purposes where everything is pre-built. – Rik Sep 06 '22 at 17:30
20

Note: The question guesses that the Docker Cloud reference is the go-to for understanding stack, and it is useful, but that isn't the authoritative source on stack vs compose -- instead that is a guide that is specific to Docker's hosted service: "Docker Cloud provides a hosted registry service with build and testing facilities." For file documentation, see the Compose file version 3 format -- although it is named "Compose", this is the authoritative place for which features work with both compose and swarm/stack, and how.

You can specify a group of Docker containers to configure and deploy in two ways:

  1. Docker compose (docker-compose up)
  2. Docker swarm (docker swarm init; docker stack deploy --compose-file docker-stack.yml mystack)

Both take a YAML file written in the Docker Compose file version 3 format. That reference is the primary source documenting both docker-compose and docker swarm/stack configuration.

However, there are specific differences between what you can do in the two yml files -- specific options, and specific naming conventions:

Options

The available service configuration options are documented on the Compose file reference page -- usually with a note at the bottom of an option entry describing it as ignored either by docker stack deploy or by docker-compose up.

For example, the following options are ignored when deploying a stack in swarm mode with a (version 3) Compose file:

build, cap_add, cap_drop, cgroup_parent, container_name, depends_on, devices, external_links, links, network_mode, restart, security_opt, stop_signal, sysctls, tmpfs (version 3-3.5), userns_mode

...while some options are ignored by docker-compose, yet work with docker stack deploy, such as:

deploy, restart_policy

When run from the command line, docker stack deploy will print warnings about which options it is ignoring:

Ignoring unsupported options: links

File naming

  • For docker-compose up the default file name is docker-compose.yml if no alternate file name is specified using -f (see the compose reference). It is common to use this default name and run the command without an argument.

  • For docker stack deploy there is no default file given in the docker stack deploy reference. You can use whatever name you want, however here are three conventions:

    1. use docker-stack.yml, as used in the official Docker for Beginners Ch.3: Deploying an app to a Swarm.
    2. use docker-cloud.yml, as used in the Docker Cloud Stack YML reference for the Docker Cloud service.
    3. use docker-compose.yml -- the old default name for the Compose file format.
JeremyDouglass
  • 1,361
  • 2
  • 18
  • 31
  • 4
    Nice overview :- ). I find it slightly annoying that the Compose file reference docs has entries that don't work with (Docker- ) Compose :- P – KajMagnus Nov 06 '18 at 15:57
  • 1
    @KajMagnus I agree, there should be a filter to see only the options you have available in either scenario. – Jens May 03 '20 at 01:37