9

Using docker stack deploy, I can see the following message:

Ignoring unsupported options: restart
  • Does it mean that restart policies are not in place?
  • Do they have to be specified outside the compose file?

You can see this message for example with the Joomla compose file available at the bottom of that page. To start the compose file:

sudo docker swarm init
sudo docker stack deploy -c stackjoomla.yml joomla
Paul Rougieux
  • 10,289
  • 4
  • 68
  • 110
  • 1
    The compose file instruction `restart:always` is deprecated. docs.docker.com explains how to create [restart policies in compose files](https://docs.docker.com/compose/compose-file/#restart_policy). The condition should be changed to `deploy: restart_policy: condition: on-failure` with [proper indentation as explained in this answer](https://stackoverflow.com/a/43566591/2641825). – Paul Rougieux Jan 05 '18 at 10:15

2 Answers2

15

A Compose YAML file is used by both docker-compose tool, for local (single-host) dev and test scenarios, and Swarm Stacks, for production multi-host concerns.

There are many settings in the Compose file which only work in one tool or the other (docker-compose up vs. docker stack deploy) because some settings are specific to dev and others specific to production clusters. It's OK that they are there, and you'll see warnings in either tool when there are settings included that the specific tool will ignore. This is commonly seen for build: settings (which are docker-compose only) and deploy: settings (which are Swarm Stacks only).

The whole goal here is a single file you can use in both tools, and the relevant sections of the compose file are used in that scenario, while the rest are ignored.

All of this can be referenced for the individual setting in the compose file documentation. If you're often working in Compose YAML, I recommend always having a tab open on this page, as I've referenced it almost daily for years, as the spec keeps changing (we're on 3.4+ now).

docker-compose does not restart containers by default, but it can if you set the single-setting restart: as documented here. But that setting doesn't work for Swarm Stacks. It will show up as a warning in a docker stack deploy to remind you that the setting will not take effect in a Swarm Stack.

Swarm Stacks use the restart_policy: under the deploy: setting, which gives finer control with multiple sub-settings. Like all Stack's, the defaults don't have to be specified in the compose file, and you'll see their default settings documented on that docs page.

There is a list on that page of the settings that won't work in a Swarm Stack, but it looks incomplete as the restart: setting should be there too. I'll submit a PR to fix that.

Also, in the Joomla example you pointed us too, that README seems out of date as well, as it includes links: in the compose example, which are depreciated as of Compose version 2, and not needed anymore (because all containers on a custom virtual network can reach each other now).

spinkus
  • 7,694
  • 4
  • 38
  • 62
Bret Fisher
  • 8,164
  • 2
  • 31
  • 36
  • 2
    PR submitted for improving restart vs. restart_policy docs: https://github.com/docker/docker.github.io/pull/5680 – Bret Fisher Jan 06 '18 at 20:17
  • 1
    Issue submitted to update Joomla template: https://github.com/joomla/docker-joomla/issues/41 – Bret Fisher Jan 06 '18 at 20:26
  • The default [restart_policy](https://docs.docker.com/compose/compose-file/#restart_policy) is `any`. What does `any` mean? – Paul Rougieux Jan 08 '18 at 17:01
  • 1
    Any means it will always recreate the container. That's the job of a declarative system like Swarm Services. You told the service you want X number of replicas/containers, and it will re-create any containers that fail/stop for any reason by default. – Bret Fisher Jan 09 '18 at 05:52
6

If you docker-compose up your application on a Docker host in standalone mode, all that Compose will do is start containers. It will not monitor the state of these containers once they are created. So it is up to you to ensure that your application will still work if a container dies. You can do this by setting a restart-policy.

If you deploy an application into a Docker swarm with docker stack deploy, things are different. A stack is created that consists of service specifications. Docker swarm then makes sure that for each service in the stack, at all times the specified number of instances is running. If a container fails, swarm will always spawn a new instance in order to match the service specification again. In this context, a restart-policy does not make any sense and the corresponding setting in the compose file is ignored.

If you want to stop the containers of your application in swarm mode, you either have to undeploy the whole stack with docker stack rm <stack-name> or scale the service to zero with docker service scale <service-name>=0.

Harald Albers
  • 1,913
  • 16
  • 20
  • 1
    Thank you for the explanation, "swarm will always spawn a new instance [...] In this context, a restart-policy does not make any sense ". Can you point to a place in the [docker swarm documentation](https://docs.docker.com/engine/swarm/) that explains that restart policies are not needed any more? – Paul Rougieux Jan 05 '18 at 18:33
  • 1
    last edit timed out, so here the full post: It's a bit more complicated. Docker-compose basically translates the settings from the compose file to `docker run` api calls. `restart` maps to `docker run --restart-policy`. `docker stack deploy` creates services, which do not have a `--restart-policy`. Therefore, the "traditional" `restart` element from the compose file is not supported in swarm mode. Note that there is a new `restart-policy` setting in docker-compose.yml https://docs.docker.com/compose/compose-file/#restart_policy that allows you to tweak restart behaviour in swarm mode. – Harald Albers Jan 08 '18 at 09:28
  • I decided to use `docker stack deploy` since it's recommended in the [get-started tutorial](https://docs.docker.com/get-started/part3/). I'm wondering if there is a documentation about the behaviour of services in a stack after a reboot of the swarm manager. The [swarm/admin_guide/](https://docs.docker.com/engine/swarm/admin_guide/) is going into further details about a quorum of manager nodes, but I'm deploying on a single server. For lack of a clearer explanation, I'll assume that the docker services started with `docker stack deploy` will always restart automatically if the server reboots. – Paul Rougieux Jan 08 '18 at 16:57
  • 1
    Yes, docker is set to start by default on boot, and Swarm services set their tasks to start when Swarm comes online. – Bret Fisher Jan 09 '18 at 05:54