Docker stacks and distributed application bundles (experimental)
Estimated reading time: 4 minutes
The functionality described on this page is marked as Experimental, and as such, may change before it becomes generally available.
A Dockerfile can be built into an image, and containers can be created from
that image. Similarly, a
docker-compose.yml can be built into a distributed
application bundle, and stacks can be created from that bundle. In that
sense, the bundle is a multi-services distributable image format.
Docker Stacks and Distributed Application Bundles started as experimental
features introduced in Docker 1.12 and Docker Compose 1.8, alongside the concept
of swarm mode, and nodes and services in the Engine API. Neither Docker Engine
nor the Docker Registry support distribution of bundles, and the concept of a
bundle is not the emphasis for new releases going forward.
If you are just getting started with Docker and want to learn the best way to deploy multi-service applications, a good place to start is the Get Started walkthrough. This shows you how to define a service configuration in a Compose file, deploy the app, and use the relevant tools and commands.
Produce a bundle
The easiest way to produce a bundle is to generate it using
from an existing
docker-compose.yml. Of course, that’s just one possible way
to proceed, in the same way that
docker build isn’t the only way to produce a
$ docker-compose bundle WARNING: Unsupported key 'network_mode' in services.nsqd - ignoring WARNING: Unsupported key 'links' in services.nsqd - ignoring WARNING: Unsupported key 'volumes' in services.nsqd - ignoring [...] Wrote bundle to vossibility-stack.dab
Create a stack from a bundle
Note: Because support for stacks and bundles is in the experimental stage, you need to install an experimental build of Docker Engine to use it.
If you’re on Mac or Windows, download the “Beta channel” version of Docker Desktop for Mac or Docker Desktop for Windows to install it. If you’re on Linux, follow the instructions in the experimental build README.
A stack is created using the
docker deploy command:
# docker deploy --help Usage: docker deploy [OPTIONS] STACK Create and update a stack Options: --file string Path to a Distributed Application Bundle file (Default: STACK.dab) --help Print usage --with-registry-auth Send registry authentication details to Swarm agents
Let’s deploy the stack created before:
# docker deploy vossibility-stack Loading bundle from vossibility-stack.dab Creating service vossibility-stack_elasticsearch Creating service vossibility-stack_kibana Creating service vossibility-stack_logstash Creating service vossibility-stack_lookupd Creating service vossibility-stack_nsqd Creating service vossibility-stack_vossibility-collector
We can verify that services were correctly created:
# docker service ls ID NAME REPLICAS IMAGE COMMAND 29bv0vnlm903 vossibility-stack_lookupd 1 nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662 /nsqlookupd 4awt47624qwh vossibility-stack_nsqd 1 nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662 /nsqd --data-path=/data --lookupd-tcp-address=lookupd:4160 4tjx9biia6fs vossibility-stack_elasticsearch 1 elasticsearch@sha256:12ac7c6af55d001f71800b83ba91a04f716e58d82e748fa6e5a7359eed2301aa 7563uuzr9eys vossibility-stack_kibana 1 kibana@sha256:6995a2d25709a62694a937b8a529ff36da92ebee74bafd7bf00e6caf6db2eb03 9gc5m4met4he vossibility-stack_logstash 1 logstash@sha256:2dc8bddd1bb4a5a34e8ebaf73749f6413c101b2edef6617f2f7713926d2141fe logstash -f /etc/logstash/conf.d/logstash.conf axqh55ipl40h vossibility-stack_vossibility-collector 1 icecrime/vossibility-collector@sha256:f03f2977203ba6253988c18d04061c5ec7aab46bca9dfd89a9a1fa4500989fba --config /config/config.toml --debug
Stacks are managed using the
docker stack command:
# docker stack --help Usage: docker stack COMMAND Manage Docker stacks Options: --help Print usage Commands: config Print the stack configuration deploy Create and update a stack rm Remove the stack services List the services in the stack tasks List the tasks in the stack Run 'docker stack COMMAND --help' for more information on a command.
Bundle file format
Distributed application bundles are described in a JSON format. When bundles
are persisted as files, the file extension is
A bundle has two top-level fields:
services. The version used
by Docker 1.12 tools is
services in the bundle are the services that comprise the app. They
correspond to the new
Service object introduced in the 1.12 Docker Engine API.
A service has the following fields:
- Image (required)
- The image that the service runs. Docker images should be referenced with full content hash to fully specify the deployment artifact for the service. Example:
- Command to run in service containers.
- Arguments passed to the service containers.
- Environment variables.
- Labels used for setting meta data on services.
- Service ports (composed of
string). A service description can only specify the container port to be exposed. These ports can be mapped on runtime hosts at the operator's discretion.
- Working directory inside the service containers.
- Username or UID (format:
- Networks that the service containers should be connected to. An entity deploying a bundle should create networks as needed.
Note: Some configuration options are not yet supported in the DAB format, including volume mounts.