Package: compose-addons
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.ContentsInstalldcao-includeUse CasesWorking with IncludesExampleUsagedcao-namespaceExampleUsagedcao-mergeUse CasesUsageInstallCurrently the only install option is pippipinstallcompose-addonsdcao-includeGiven 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 CasesIf 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 thedocker-compose.ymlfrom 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 coredocker-compose.ymlwould only contain the core services. Thecompose-admin.ymlwould include thedocker-compose.ymland 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 coredocker-compose.ymlwould remain the same for all
environments, butdocker-compose-dev.ymlcould include the “core”
services, and add additional service, like database or proxies.Working with Includesdcao-includeworks with a configuration that is different from thedocker-composeconfig in a few ways:an optional top levelincludekey, which contains a list of urls (which
may be local file paths, http(s) urls, or s3 paths)a required top levelnamespacekey, which is used by a config to link
to services in an included file. For example, if a config includeshttp://example.com/compositions/servicea.yamlwhich has anamespaceofservicea, all “public” services inservicea.yamlshould start
withservicea..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 nobuildkeys in any service, and no
host volumes.ExampleAn example composition file with includes:include:-http://example.com/compositions/servicea.yaml-http://example.com/compositions/serviceb.yamlnamespace:coreweb:image:example/service_a:latestlinks:['servicea.web','serviceb.api']servicea.yamlmight look something like thisnamespace:serviceaservicea.web:image:services/a:latestserviceb.yamlmight look something like thisnamespace:servicebserviceb.api:image:services/b:latestUsageTo usedcao-includewithdocker-composeyou have a couple options:Use it with a pipe to stdin:dcao-includecompose-with-includes.yml|docker-compose-f-up-dUse it once to generate a new file:dcao-include-odocker-compose.ymlcompose-with-includes.ymldocker-composeup-ddocker-composepsdcao-namespaceGiven a standarddocker-compose.ymlfile, add a namespace key, and prefix
all instances of service names with that namespace. This command is used to
prepare a standarddocker-compose.ymlfile for being used as an include
bydcao-include. This could be considered the “export” step required
before a compose file can be included by another project.ExampleGiven adocker-compose.yml:web:image:example.com/web:latestlinks:['db']volumes_from:['configs']db:image:example.com/db:latestconfigs:image:example.com/configs:latestrunningdcao-namespacedocker-compose.ymlmyservicewould producenamespace:myservicemyservice.web:image:example.com/web:latestlinks:['myservice.db:db']volumes_from:['myservice.configs']myservice.db:image:example.com/db:latestmyservice.configs:image:example.com/configs:latestUsageFirst generate the namespaced configdcao-namespace-omyservice.ymldocker-compose.ymlmyserviceNext you’ll want to makemyservice.ymlavailable to other services. In this
example we’ll assume we’re using an s3 bucketawss3cpmyservice.ymls3://some-bucket/compose-registry/myservice.ymlNow we can use that configuration as an include in another service. In a
different servicescompose-with-includes.yml(which will be consumed bydcao-include)include:-s3://some-bucket/compose-registry/myservice.ymldcao-mergeMergedocker-compose.ymlconfiguration files by overriding values in the
base configuration with values from other files. It is used to transform a
configuration without having to duplicate any fields that should remain
consistent.Use CasesOften 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 withADD(orCOPY). You could use anoverrides-dev.ymlto add
volumes to the configuration, and skip that step during CI.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 outside of version control.If adocker-compose.ymlcontainsbuilddirectives for local
development, but needsimagedirectives in other environments (testing,
stage, prod, etc), merge can be used to rewritebuildtoimagewith
the correct image tag.UsageTo rewrite a configuration to use image instead of build, and remove any host
specific configuration:dcao-merge-oexport.ymldocker-compose.ymlcompose-overrides.ymlWheredocker-compose.ymlis:web:build:.links:['db']volumes:['./logs:/app/logs']db:build:database/andcompose-overrides.yml:web:image:example.com/web:latestvolumes:[]db:image:example.com/db:latestwould produce anexport.ymlweb:image:example.com/web:latestlinks:['db']volumes:[]db:image:example.com/db:latest