Skip to main content

Tools to supplement

Project description

A set of command line tools to supplement the features already available in docker-compose. These tools generally focus on development or testing environment use-cases.


Currently the only install option is pip with git url

pip install git+


Given a docker-compose.yml file, fetch each configuration in the include section and merge it into a base docker-compose.yml. If any of the included files have include sections continue to fetch and merge each of them until there are no more files to include.

Use Cases

  • If you have a service-oriented architecture, where each of your services is developed and deployed in a separate code repo, and each has its own docker-compose.yml. When you want to create a full testing or development environment for an individual service, you need to include all the downstream services. Instead of duplicating the topology of each downstream service, you can include the docker-compose.yml from the downstream service. Including (instead of duplicating) this topology allows you to change dependencies in a single place without worrying about breaking the test suite of dependent services.
  • If the scope of your composition can change based on the task you’re performing. Your application might have a “core” set of services that are always run, and some adhoc, or administrative services that are only run sometimes. You can split your composition into two (or more) files. The core docker-compose.yml would only contain the core services. The compose-admin.yml would include the docker-compose.yml and add extra services which could link to or use volumes from the core services, without having to duplicate any of the service configuration.
  • If your composition varies by environment (dev vs prod). Similar to the case above, the core docker-compose.yml would remain the same for all environments, but docker-compose-dev.yml could include the “core” services, and add additional service, like database or proxies.

Working with Includes

dcao-include works with a configuration that is different from the docker-compose config in a few ways:

  • an optional top level include key, which contains a list of urls (which may be local file paths, http(s) urls, or s3 paths)
  • a required top level namespace key, which is used by a config to link to services in an included file. For example, if a config includes which has a namespace of servicea, all “public” services in servicea.yaml should start with servicea..
  • since configuration can be included from a remote url, or different directories, the configuration should not include anything that depends on the host. There should be no build keys in any service, and no host volumes.


An example composition file with includes:


namespace: core

    image: example/service_a:latest
    links: ['servicea.web', 'serviceb.api']

servicea.yaml might look something like this

namespace: servicea

    image: services/a:latest

serviceb.yaml might look something like this

namespace: serviceb

    image: services/b:latest


To use dcao-include with docker-compose you have a couple options:

Use it with a pipe to stdin:

dcao-include compose-with-includes.yml | docker-compose -f - up -d

Use it once to generate a new file:

dcao-include -o docker-compose.yml compose-with-includes.yml
docker-compose up -d
docker-compose ps


Given a standard docker-compose.yml file, add a namespace key, and prefix all instances of service names with that namespace. This command is used to prepare a standard docker-compose.yml file for being used as an include by dcao-include.


First general the namespaced config

dcao-namespace -o myservice.yml docker-compose.yml myservice

Next you’ll want to make myservice.yml available to other services. In this example we’ll assume we’re using an s3 bucket

aws s3 cp myservice.yml s3://some-bucket/compose-registry/myservice.yml

Now we can use that configuration as an include in another service. In a different services compose-with-includes.yml (which will be consumed by dcao-include)

    - s3://some-bucket/compose-registry/myservice.yml


Merge docker-compose.yml configuration files by overriding values in the base configuration with values from other files.

Use Cases

  • Often in development you’ll want to include code using a volume for faster iteration, but for testing on a CI you want to include the source in the container with ADD. You could use an overrides-dev.yml to add volumes to the configuration.
  • If the composition is running on a shared host each developer needs to use a different host port. This variation can be included in a file maintained by each developer, separate from the source repo.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for compose-addons, version 0.2.0
Filename, size File type Python version Upload date Hashes
Filename, size compose-addons-0.2.0.tar.gz (6.3 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page