Docker Cloud stack file YAML referenceEstimated reading time: 9 minutes
A stack is a collection of services that make up an application in a specific environment. Learn more about stacks for Docker Cloud here. A stack file is a file in YAML format that defines one or more services, similar to a
docker-compose.yml file for Docker Compose but with a few extensions. The default name for this file is
Looking for information on stack files for Swarm? A good place to start is the Compose reference file, particularly the section on
deploy key and its sub-options, and the reference on Docker stacks. Also, the new Getting Started tutorial demos use of a stack file to deploy an application to a swarm.
Stack file example
Below is an example
lb: image: dockercloud/haproxy links: - web ports: - "80:80" roles: - global web: image: dockercloud/quickstart-python links: - redis target_num_containers: 4 redis: image: redis
Each key defined in
docker-cloud.yml creates a service with that name in Docker Cloud. In the example above, three services are created:
redis. Each service is a dictionary whose possible keys are documented below.
image key is mandatory. Other keys are optional and are analogous to their Docker Cloud Service API counterparts.
The image used to deploy this service. This is the only mandatory key.
image: drupal image: dockercloud/hello-world image: my.registry.com/redis
Whether the containers for this service should be terminated if they stop (default:
no, possible values:
Whether to redeploy the containers of the service when its image is updated in Docker Cloud registry (default:
Add or drop container capabilities. See
man 7 capabilities for a full list.
cap_add: - ALL cap_drop: - NET_ADMIN - SYS_ADMIN
Specify an optional parent cgroup for the container.
Override the default command in the image.
command: echo 'Hello World!'
Container distribution among nodes (default:
emptiest_node, possible values:
every_node). Learn more here.
List of device mappings. Uses the same format as the
--device docker client create option.
devices: - "/dev/ttyUSB0:/dev/ttyUSB0"
Specify custom DNS servers. Can be a single value or a list.
dns: 126.96.36.199 dns: - 188.8.131.52 - 184.108.40.206
Specify custom DNS search domains. Can be a single value or a list.
dns_search: example.com dns_search: - dc1.example.com - dc2.example.com
A list of environment variables to add in the service’s containers at launch. The environment variables specified here override any image-defined environment variables. You can use either an array or a dictionary format.
environment: PASSWORD: my_password
environment: - PASSWORD=my_password
When you use the Docker Cloud CLI to create a stack, you can use the environment variables defined locally in your shell to define those in the stack. This is useful if you don’t want to store passwords or other sensitive information in your stack file:
environment: - PASSWORD
Expose ports without publishing them to the host machine - they’ll only be accessible from your nodes in Docker Cloud.
udp ports can be specified with a
expose: - "80" - "90/udp"
Add hostname mappings. Use the same values as the docker client
extra_hosts: - "somehost:220.127.116.11" - "otherhost:18.104.22.168"
Add metadata to containers using Docker Engine labels. You can use either an array or a dictionary.
We recommend using reverse-DNS notation to prevent your labels from conflicting with those used by other software.
labels: com.example.description: "Accounting webapp" com.example.department: "Finance" com.example.label-with-empty-value: "" labels: - "com.example.description=Accounting webapp" - "com.example.department=Finance" - "com.example.label-with-empty-value"
Link to another service.
Either specify both the service unique name and the link alias (
SERVICE:ALIAS), or just the service unique name (which will also be used for the alias). If a service you want to link to is part of a different stack, specify the external stack name too.
- If the target service belongs to this stack, its service unique name is its service name.
- If the target service does not belong to any stacks (it is a standalone service), its service unique name is its service name.
- If the target service belongs to another stack, its service unique name is its service name plus the service stack name, separated by a period (
links: - mysql - redis:cache - amqp.staging:amqp
Environment variables are created for each link that Docker Cloud resolves to the containers IPs of the linked service. More information here.
Networking mode. Only “bridge” and “host” options are supported for now.
Sets the PID mode to the host PID mode. This turns on sharing between container and the host operating system the PID address space. Containers launched with this (optional) flag will be able to access and be accessed by other containers in the namespace belonging to the host running the Docker daemon.
Expose ports. Either specify both ports (
HOST:CONTAINER), or just the container port (a random host port will be chosen).
udp ports can be specified with a
ports: - "80" - "443:443" - "500/udp" - "4500:4500/udp" - "49022:22"
Whether to start the containers with Docker Engine’s privileged flag set or not (default:
Whether the containers for this service should be restarted if they stop (default:
no, possible values:
A list of Docker Cloud API roles to grant the service. The only supported value is
global, which creates an environment variable
DOCKERCLOUD_AUTH used to authenticate against Docker Cloud API. Learn more here.
roles: - global
Override the default labeling scheme for each container.
security_opt: - label:user:USER - label:role:ROLE
Whether the containers should be launched and scaled in sequence (default:
false). Learn more here.
Indicates the deploy tags to select the nodes where containers are created.
tags: - staging - web
The number of containers to run for this service (default:
Mount paths as volumes, optionally specifying a path on the host machine (
HOST:CONTAINER), or an access mode (
volumes: - /etc/mysql - /sys:/sys - /etc:/etc:ro
Mount all of the volumes from another service by specifying a service unique name.
- If the target service belongs to this stack its service unique name is its service name.
- If the target service does not belong to any stack its service unique name is its service name.
- If the target service belongs to another stack its service unique name is its service name plus the service stack name, separated by “.”. Learn more here.
volumes_from: - database - mongodb.staging
Single value keys analogous to a
docker run counterpart
working_dir: /app entrypoint: /app/entrypoint.sh user: root hostname: foo domainname: foo.com mac_address: 02:42:ac:11:65:43 cpu_shares: 512 cpuset: 0,1 mem_limit: 100000m memswap_limit: 200000m privileged: true read_only: true stdin_open: true tty: true
Unsupported Docker-compose keys
Stack files (
docker-cloud.yml) were designed with
docker-compose.yml in mind to maximize compatibility. However the following keys used in Compose are not supported in Docker Cloud stackfiles:
build external_links env_file