Basics — The Cage way
Standardized application structure
Much like the “Rails way” defined a convention for structuring a standalone web application, Cage offers a uniform format for describing a broad class of multi-service Docker applications.
myproject/ ├── config │ └── project.yml └── pods ├── common.env ├── frontend.yml └── targets └── test └── common.env
config/dir contains a
project.ymlfor specifying your application-level Cage config.
pods/dir is the heart of the Cage repo, containing a
.ymlfile for each pod of services in your application.
pods/podname.ymlfile lists and describes the one or more services included in that pod. Each service description includes a Docker image name, repo location, ports, and a service-level “API” for testing and shell access.
pods/common.envfile specifies environment variables that are made available to all services in any pod. Each pod can also have its own
pods/podname.ymlfile for pod-specific environment variables.
targets/dir contains a subdir for each target that requires special overrides, either to the pod definition or environment variables.
cage relate to
docker-compose is the standard tool for working with multiple Docker
cage acts as a wrapper around
docker-composewill generally require multiple
docker-compose.ymlfiles for larger projects, but it offers no conventions for organizing them.
cageprovides conventions and tools to make this workflow easier.
docker-composeprovides limited support for working with the source code for existing images.
cagemakes this simple, allowing you to clone the git repository for a service and mount the source code into a pre-built image for easy editing.
cagegives you a “birds-eye view” of all your microservices to make it easier to write end-to-end integration and acceptance tests.
cageprovides support for secret-handling, either via a centralized text file or Hashicorp’s Vault.
cage makes it easy to use
docker-compose with large,
Cage draws its terminology from the container ecosystem, including Docker and Kubernetes.
A service is an individual component of your application, generally represented in version control as a single repository. Each service must include a
Dockerfilethat allows it to be loaded into a container.
A container follows the standard Docker definition, wrapping an individual service for use in the application.
A source is where a service’s code is found—this could be a pre-built container image or a local source tree.
A target is also known as an “environment,” although we avoid that term to reduce confusion with environment variables, which Cage actively manages. Common targets include
test(for running test suites), and
A pod is a tightly-linked group of containers that are always deployed together. Kubernetes offers a more complete definition. If you’re using Amazon’s ECS, a pod corresponds to an ECS “task” or “service”. If you’re using Docker Swarm, a pod corresponds to a single docker-compose.xml file full of services that you always launch as a single unit.