What's the difference between a stack file and a Compose file?

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/

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.