Setup — How to use Cage with your application

Installing Cage

If you’ve never used Cage before, you’ll need to install it on your development machine.

  1. First, you need to install Docker and make sure that you have at least version 1.8.1 of Docker Compose.

  2. Download the latest cage binary for your platform.

  3. Install it:

$ 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:

$ 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.

The 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

The cage new command starts us off with a few pods that serve as examples.

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.

cd ~/code/myproject

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
  Cloned at src/rails_hello (mounted)

Describe your application

Next: On GitHub