Setup — How to use Cage with your application
If you’ve never used Cage before, you’ll need to install it on your development machine.
First, you need to install Docker and make sure that you have at least version 1.8.1 of Docker Compose.
Download the latest
cagebinary for your platform.
$ unzip cage-*.zip $ sudo cp cage /usr/local/bin/ $ rm cage-*.zip cage
If you have Rust installed, you can also
install it using
$ cargo install cage
Create a Cage repo
With Cage, you define the structure of your application in code. We recommend you store it in its own repo in version control—this lets you track changes and collaborate with your colleagues.
cage new command lets you “stub out” a skeleton Cage application:
$ cd ~/code $ cage new myproject $ cd myproject/ $ tree . ├── config │ └── project.yml └── pods ├── common.env ├── db.metadata.yml ├── db.yml ├── frontend.yml ├── migrate.metadata.yml ├── migrate.yml └── targets ├── development │ └── common.env ├── production │ └── common.env └── test └── common.env
cage new command starts us off with a few pods that serve as examples.
frontendis a simple front-end web pod that includes a single service—which happens to use Rails but could use any web framework (e.g. Express).
frontend.ymldescribes that pod and the Rails-based
webservice in it. Comments in the file explain its structure.
dbis a straightforward database pod that includes a single Postgres service.
db.ymldescribes the pod and its Postgres service. The associated
db.metadata.ymlindicates that this pod should only be started in the development target.
rakeis a “task pod” — its
rake.ymlfile actually references the same image as
frontend, but with a
entrypointkey that makes it easy to run rake tasks in the container. The associated
rake.metadata.ymldeclares this “task” purpose.
Explore the sample application
After using the
cage new command as described above, we can explore the sample application that Cage generates in your new Cage repo.
First, let’s pull any associated Docker images listed in your Cage config:
$ cage pull
Let’s start by bringing up our local database server and initializing our database:
$ cage up db $ cage run rake db:create $ cage run rake db:migrate
Now let’s bring up the rest of our multi-service application!
$ cage up
Now we can look at our web app!
$ open http://localhost:3000
What if we want to make changes to one of the application’s services, while using pre-built Docker images for everything else? We use the
cage mount command to “check out” the service’s source locally.
$ cage source mount rails_hello # Restart our Rails app using local source code. $ cage up $ $EDITOR src/rails_hello
After we’ve made some changes, we’ll want to run tests:
$ cage test web
Some one-time tasks are important enough to have a task pod defined, such as
rake in the example application:
$ cage run rake -T
And there are always times when you just need to shell into the service:
$ cage shell web
You can always check to see what source trees are available, and which are currently mounted into services:
$ cage source ls rails_hello https://github.com/faradayio/rails_hello.git Cloned at src/rails_hello (mounted)
Describe your application
At the very least, you’ll need a single
pods/master.ymlthat lists and describes each of the services in your application. But we recommend thinking carefully about the relationships between your services and separating them into logical pods, each with its own
You’ll also likely want a
pods/common.envthat defines environment variables for your application.
Next: On GitHub