Fig

Punctual, lightweight development environments using Docker.

Fig is a tool for defining and running isolated application environments. You define the services which comprise your app in a simple, version-controllable YAML configuration file that looks like this:

web:
  build: .
  links:
   - db
  ports:
   - 8000:8000
db:
  image: orchardup/postgresql

Then type fig up, and Fig will start and run your entire app:

$ fig up
Pulling image orchardup/postgresql...
Building web...
Starting example_db_1...
Starting example_web_1...
example_db_1 | 2014-01-02 14:47:18 UTC LOG:  database system is ready to accept connections
example_web_1 |  * Running on http://0.0.0.0:5000/

There are commands to:

• start, stop and rebuild services
• view the status of running services
• tail running services' log output
• run a one-off command on a service

Fig is a project from Orchard, a Docker hosting service. Follow us on Twitter to keep up to date with Fig and other Docker news.

Getting started

Let's get a basic Python web app running on Fig. It assumes a little knowledge of Python, but the concepts should be clear if you're not familiar with it.

First, install Docker. If you're on OS X, you can use docker-osx:

$ curl https://raw.github.com/noplay/docker-osx/master/docker > /usr/local/bin/docker
$ chmod +x /usr/local/bin/docker
$ docker version

Docker has guides for Ubuntu and other platforms in their documentation.

Next, install Fig:

$ sudo pip install fig

You'll want to make a directory for the project:

$ mkdir figtest
$ cd figtest

Inside this directory, create app.py, a simple web app that uses the Flask framework and increments a value in Redis:

from flask import Flask
from redis import Redis
import os
app = Flask(__name__)
redis = Redis(
    host=os.environ.get('FIGTEST_REDIS_1_PORT_6379_TCP_ADDR'),
    port=int(os.environ.get('FIGTEST_REDIS_1_PORT_6379_TCP_PORT'))
)

@app.route('/')
def hello():
    redis.incr('hits')
    return 'Hello World! I have been seen %s times.' % redis.get('hits')

if __name__ == "__main__":
    app.run(host="0.0.0.0", debug=True)

We define our Python dependencies in a file called requirements.txt:

flask
redis

And we define how to build this into a Docker image using a file called Dockerfile:

FROM stackbrew/ubuntu:13.10
RUN apt-get -qq update
RUN apt-get install -y python python-pip
ADD . /code
WORKDIR /code
RUN pip install -r requirements.txt
EXPOSE 5000
CMD python app.py

That tells Docker to create an image with Python and Flask installed on it, run the command python app.py, and open port 5000 (the port that Flask listens on).

We then define a set of services using fig.yml:

web:
  build: .
  ports:
   - 5000:5000
  volumes:
   - .:/code
  links:
   - redis
redis:
  image: orchardup/redis

This defines two services:

• web, which is built from Dockerfile in the current directory. It also says to forward the exposed port 5000 on the container to port 5000 on the host machine, connect up the redis service, and mount the current directory inside the container so we can work on code without having to rebuild the image.
• redis, which uses the public image orchardup/redis.

Now if we run fig up, it'll pull a Redis image, build an image for our own app, and start everything up:

$ fig up
Pulling image orchardup/redis...
Building web...
Starting figtest_redis_1...
Starting figtest_web_1...
figtest_redis_1 | [8] 02 Jan 18:43:35.576 # Server started, Redis version 2.8.3
figtest_web_1 |  * Running on http://0.0.0.0:5000/

Open up http://localhost:5000 in your browser (or http://localdocker:5000 if you're using docker-osx). That's it!

You can also pass the -d flag to fig up to run your services in the background, and use fig ps to see what is currently running:

$ fig up -d
Starting figtest_redis_1...
Starting figtest_web_1...
$ fig ps
        Name                 Command            State       Ports
-------------------------------------------------------------------
figtest_redis_1   /usr/local/bin/run         Up
figtest_web_1     /bin/sh -c python app.py   Up      5000->5000/tcp

fig run allows you to run one-off commands for your services. For example, to see what environment variables are available to the web service:

$ fig run web env

Run fig --help to see what other commands are available. You'll probably want to stop them when you've finished:

$ fig stop

That's more-or-less how Fig works. See the reference section below for full details on the commands, configuration file and environment variables.

Reference

fig.yml

Each service defined in fig.yml must specify exactly one of image or build. Other keys are optional, and are analogous to their docker run command-line counterparts.

As with docker run, options specified in the Dockerfile (e.g. CMD, EXPOSE, VOLUME, ENV) are respected by default - you don't need to specify them again in fig.yml.

-- Tag or partial image ID. Can be local or remote - Fig will attempt to pull if it doesn't exist locally.
image: ubuntu
image: orchardup/postgresql
image: a4bc65fd

-- Path to a directory containing a Dockerfile. Fig will build and tag it with a generated name, and use that image thereafter.
build: /path/to/build/dir

-- Override the default command.
command: bundle exec thin -p 3000

-- Link to containers in another service (see "Communicating between containers").
links:
 - db
 - redis

-- Expose ports. Either specify both ports (HOST:CONTAINER), or just the container port (a random host port will be chosen).
ports:
 - 3000
 - 8000:8000

-- Map volumes from the host machine (HOST:CONTAINER).
volumes:
 - cache/:/tmp/cache

-- Add environment variables.
environment:
  RACK_ENV: development

Environment variables

Fig uses Docker links to expose services' containers to one another. Each linked container injects a set of environment variables, each of which begins with the uppercase name of the container.

name_PORT
Full URL, e.g. MYAPP_DB_1_PORT=tcp://172.17.0.5:5432

name_PORT_num_protocol
Full URL, e.g. MYAPP_DB_1_PORT_5432_TCP=tcp://172.17.0.5:5432

name_PORT_num_protocol_ADDR
Container's IP address, e.g. MYAPP_DB_1_PORT_5432_TCP_ADDR=172.17.0.5

name_PORT_num_protocol_PORT
Exposed port number, e.g. MYAPP_DB_1_PORT_5432_TCP_PORT=5432

name_PORT_num_protocol_PROTO
Protocol (tcp or udp), e.g. MYAPP_DB_1_PORT_5432_TCP_PROTO=tcp

name_NAME
Fully qualified container name, e.g. MYAPP_DB_1_NAME=/myapp_web_1/myapp_db_1