From 01d0e49a1c180ed1fa1a648df3c6debc07053b66 Mon Sep 17 00:00:00 2001
From: Aanand Prasad <aanand.prasad@gmail.com>
Date: Mon, 27 Jan 2014 15:03:21 +0000
Subject: [PATCH] New website

---
 docs/_layouts/default.html |  46 ++++++++---
 docs/cli.md                |  75 ++++++++++++++++++
 docs/css/fig.css           | 124 ++++++++++++++++++++---------
 docs/django.md             |  90 +++++++++++++++++++++
 docs/env.md                |  29 +++++++
 docs/index.md              | 157 +++----------------------------------
 docs/install.md            |  23 ++++++
 docs/rails.md              |  98 +++++++++++++++++++++++
 docs/yml.md                |  43 ++++++++++
 9 files changed, 487 insertions(+), 198 deletions(-)
 create mode 100644 docs/cli.md
 create mode 100644 docs/django.md
 create mode 100644 docs/env.md
 create mode 100644 docs/install.md
 create mode 100644 docs/rails.md
 create mode 100644 docs/yml.md
diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
index 796d0d4ed..b76ed4388 100644
--- a/docs/_layouts/default.html
+++ b/docs/_layouts/default.html
@@ -4,29 +4,49 @@
     <meta charset="utf-8">
     <title>{{ page.title }}</title>
     <meta name="viewport" content="width=device-width, initial-scale=1">
-    <link href='http://fonts.googleapis.com/css?family=Lilita+One|Lato:300,400' rel='stylesheet' type='text/css'>
+    <link href='http://fonts.googleapis.com/css?family=Lilita+One|Lato:300,400,700' rel='stylesheet' type='text/css'>
     <link rel="stylesheet" type="text/css" href="css/bootstrap.min.css">
     <link rel="stylesheet" type="text/css" href="css/fig.css">
   </head>
   <body>
-    <div class="github-top top-notice">
-      <a href="https://github.com/orchardup/fig" class="btn btn-large">View on Github</a>
-    </div>
-
     <div class="container">
-      <h1 class="logo">
+      <div class="logo mobile-logo">
         <img src="img/logo.png">
         Fig
-      </h1>
-
-      <iframe src="http://ghbtns.com/github-btn.html?user=orchardup&repo=fig&type=watch&count=true" allowtransparency="true" frameborder="0" scrolling="0" width="100" height="20"></iframe>
-      <a href="https://twitter.com/share" class="twitter-share-button" data-url="http://orchardup.github.io/fig/">Tweet</a>
+      </div>
 
       <div class="content">{{ content }}</div>
-    </div>
 
-    <div class="github-bottom">
-      <a href="https://github.com/orchardup/fig" class="btn btn-large">View on Github</a>
+      <div class="sidebar">
+        <h1 class="logo">
+          <img src="img/logo.png">
+          Fig
+        </h1>
+
+        <ul class="nav">
+          <li><a href="index.html">Home</a></li>
+          <li><a href="install.html">Install</a></li>
+          <li><a href="rails.html">Get started with Rails</a></li>
+          <li><a href="django.html">Get started with Django</a></li>
+        </ul>
+        <ul class="nav">
+          <li>Reference:</li>
+          <ul>
+            <li><a href="yml.html">fig.yml</a></li>
+            <li><a href="cli.html">Commands</a></li>
+            <li><a href="env.html">Environment variables</a></li>
+          </ul>
+        </ul>
+        <ul class="nav">
+          <li><a href="https://github.com/orchardup/fig">Fig on GitHub</a></li>
+          <li><a href="https://twitter.com/orchardup">Follow us on Twitter</a></li>
+        </ul>
+
+        <div class="badges">
+          <iframe src="http://ghbtns.com/github-btn.html?user=orchardup&amp;repo=fig&amp;type=watch&amp;count=true" allowtransparency="true" frameborder="0" scrolling="0" width="100" height="20"></iframe>
+          <a href="https://twitter.com/share" class="twitter-share-button" data-url="http://orchardup.github.io/fig/">Tweet</a>
+        </div>
+      </div>
     </div>
       <script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script>
     <script>
diff --git a/docs/cli.md b/docs/cli.md
new file mode 100644
index 000000000..23ac20407
--- /dev/null
+++ b/docs/cli.md
@@ -0,0 +1,75 @@
+---
+layout: default
+title: Fig CLI reference
+---
+
+CLI reference
+=============
+
+Most commands are run against one or more services. If the service is omitted, it will apply to all services.
+
+Run `fig [COMMAND] --help` for full usage.
+
+## build
+
+Build or rebuild services.
+
+Services are built once and then tagged as `project_service`, e.g. `figtest_db`. If you change a service's `Dockerfile` or the contents of its build directory, you can run `fig build` to rebuild it.
+
+## help
+
+Get help on a command.
+
+## kill
+
+Force stop service containers.
+
+## logs
+
+View output from services.
+
+## ps
+
+List containers.
+
+## rm
+
+Remove stopped service containers.
+
+
+## run
+
+Run a one-off command on a service.
+
+For example:
+
+    $ fig run web python manage.py shell
+
+Note that this will not start any services that the command's service links to. So if, for example, your one-off command talks to your database, you will need to run `fig up -d db` first.
+
+## scale
+
+Set number of containers to run for a service.
+
+Numbers are specified in the form `service=num` as arguments.
+For example:
+
+    $ fig scale web=2 worker=3
+
+## start
+
+Start existing containers for a service.
+
+## stop
+
+Stop running containers without removing them. They can be started again with `fig start`.
+
+## up
+
+Build, (re)create, start and attach to containers for a service.
+
+By default, `fig up` will aggregate the output of each container, and when it exits, all containers will be stopped. If you run `fig up -d`, it'll start the containers in the background and leave them running.
+
+If there are existing containers for a service, `fig up` will stop and recreate them (preserving mounted volumes with [volumes-from]), so that changes in `fig.yml` are picked up.
+
+[volumes-from]: http://docs.docker.io/en/latest/use/working_with_volumes/
diff --git a/docs/css/fig.css b/docs/css/fig.css
index 48fef5e21..381c47ad7 100644
--- a/docs/css/fig.css
+++ b/docs/css/fig.css
@@ -52,61 +52,98 @@ img {
   max-width: 100%;
 }
 
-/* Customize container */
-@media (min-width: 768px) {
-  .container {
-    max-width: 730px;
-  }
-}
-
-@media (min-width: 481px) {
-  .github-top {
-    position: absolute;
-    top: 0;
-    right: 0;
-  }
-}
-
-.content h1 {
-  display: none;
+.container {
+  margin-left: 0;
 }
 
 .logo {
-  text-align: center;
   font-family: 'Lilita One', sans-serif;
   font-size: 80px;
-  color: #a41211;
   margin: 20px 0 40px 0;
+  color: #a41211;
 }
 
 .logo img {
-  width: 100px;
+  width: 80px;
   vertical-align: -17px;
 }
 
-@media (min-width: 481px) {
-  .logo {
-    font-size: 96px;
-    margin-top: 40px;
-  }
-  .logo img {
-    vertical-align: -40px;
-    width: 150px;
-    margin-right: 20px;
-  }
-}
-
-.github-top,
-.github-bottom {
+.mobile-logo {
   text-align: center;
 }
 
-.github-top {
-  margin: 30px;
+.sidebar {
+  font-size: 16px;
 }
 
-.github-bottom {
-  margin: 60px 0;
+.sidebar a {
+  color: #a41211;
+}
+
+@media (max-width: 767px) {
+  .sidebar {
+    text-align: center;
+    margin-top: 40px;
+  }
+
+  .sidebar .logo {
+    display: none;
+  }
+}
+
+@media (min-width: 768px) {
+  .mobile-logo {
+    display: none;
+  }
+
+  .logo {
+    margin-top: 40px;
+  }
+
+  .content h1 {
+    margin: 60px 0 55px 0;
+  }
+
+  .sidebar {
+    position: fixed;
+    top: 0;
+    left: 0;
+    bottom: 0;
+    width: 280px;
+    overflow-y: auto;
+    padding-left: 40px;
+    border-right: 1px solid #ccc;
+  }
+
+  .content {
+    margin-left: 320px;
+    max-width: 650px;
+  }
+}
+
+.nav {
+  margin: 20px 0;
+}
+
+.nav li a {
+  display: block;
+  padding: 8px 0;
+  line-height: 1.2;
+  text-decoration: none;
+}
+
+.nav li a:hover, .nav li a:focus {
+  text-decoration: underline;
+  background: none;
+}
+
+.nav ul {
+  padding-left: 20px;
+  list-style: none;
+}
+
+.badges {
+  margin: 40px 0;
 }
 
 a.btn {
@@ -120,5 +157,14 @@ a.btn:hover {
   color: white;
 }
 
+.strapline {
+  font-size: 40px;
+  display: block;
+  line-height: 1.2;
+  margin-top: 25px;
+  margin-bottom: 35px;
+}
 
-
+strong {
+  font-weight: 700;
+}
diff --git a/docs/django.md b/docs/django.md
new file mode 100644
index 000000000..251a61901
--- /dev/null
+++ b/docs/django.md
@@ -0,0 +1,90 @@
+---
+layout: default
+title: Getting started with Fig and Django
+---
+
+Getting started with Fig and Django
+===================================
+
+Let's use Fig to set up and run a Django/PostgreSQL app. Before starting, you'll need to have [Fig installed](install.html).
+
+Let's set up the three files that'll get us started. First, our app is going to be running inside a Docker container which contains all of its dependencies. We can define what goes inside that Docker container using a file called `Dockerfile`. It'll contain this to start with:
+
+    FROM orchardup/python:2.7
+    RUN mkdir /code
+    WORKDIR /code
+    ADD requirements.txt /code/
+    RUN pip install -r requirements.txt
+    ADD . /code/
+
+That'll install our application inside an image with Python installed alongside all of our Python dependencies.
+
+Second, we define our Python dependencies in a file called `requirements.txt`:
+
+    Django
+
+Simple enough. Finally, this is all tied together with a file called `fig.yml`. It describes the services that our app comprises of (a web server and database), what Docker images they use, how they link together, what volumes will be mounted inside the containers and what ports they expose.
+
+    db:
+      image: orchardup/postgresql
+      ports:
+        - 5432
+    web:
+      build: .
+      command: python manage.py runserver 0.0.0.0:8000
+      volumes:
+        - .:/code
+      ports:
+        - 8000:8000
+      links:
+        - db
+
+See the [`fig.yml` reference]() for more information on how it works.
+
+We can now start a Django project using `fig run`:
+
+    $ fig run web django-admin.py startproject figexample .
+
+First, Fig will build an image for the `web` service using the `Dockerfile`. It will then run `django-admin.py startproject figexample .` inside a container using that image.
+
+This will generate a Django app inside the current directory:
+
+    $ ls
+    Dockerfile       fig.yml          figexample       manage.py        requirements.txt
+
+First thing we need to do is set up the database connection. Replace the `DATABASES = ...` definition in `figexample/settings.py` to read:
+
+    DATABASES = {
+        'default': {
+            'ENGINE': 'django.db.backends.postgresql_psycopg2',
+            'NAME': 'docker',
+            'USER': 'docker',
+            'PASSWORD': 'docker',
+            'HOST': os.environ.get('MYAPP_DB_1_PORT_5432_TCP_ADDR'),
+            'PORT': os.environ.get('MYAPP_DB_1_PORT_5432_TCP_PORT'),
+        }
+    }
+
+Then, run `fig up`:
+
+    Recreating myapp_db_1...
+    Recreating myapp_web_1...
+    Attaching to myapp_db_1, myapp_web_1
+    myapp_db_1 |
+    myapp_db_1 | PostgreSQL stand-alone backend 9.1.11
+    myapp_db_1 | 2014-01-27 12:17:03 UTC LOG:  database system is ready to accept connections
+    myapp_db_1 | 2014-01-27 12:17:03 UTC LOG:  autovacuum launcher started
+    myapp_web_1 | Validating models...
+    myapp_web_1 |
+    myapp_web_1 | 0 errors found
+    myapp_web_1 | January 27, 2014 - 12:12:40
+    myapp_web_1 | Django version 1.6.1, using settings 'figexample.settings'
+    myapp_web_1 | Starting development server at http://0.0.0.0:8000/
+    myapp_web_1 | Quit the server with CONTROL-C.
+
+And your Django app should be running at localhost:3000 (or localdocker:3000 if you're using docker-osx).
+
+You can also run management commands with Docker. To set up your database, for example, run `fig up` and in other terminal run:
+
+    $ fig run web python manage.py syncdb
+
diff --git a/docs/env.md b/docs/env.md
new file mode 100644
index 000000000..dcfebd28e
--- /dev/null
+++ b/docs/env.md
@@ -0,0 +1,29 @@
+---
+layout: default
+title: Fig environment variables reference
+---
+
+Environment variables reference
+===============================
+
+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.
+
+<b><i>name</i>\_PORT</b><br>
+Full URL, e.g. `MYAPP_DB_1_PORT=tcp://172.17.0.5:5432`
+
+<b><i>name</i>\_PORT\_<i>num</i>\_<i>protocol</i></b><br>
+Full URL, e.g. `MYAPP_DB_1_PORT_5432_TCP=tcp://172.17.0.5:5432`
+
+<b><i>name</i>\_PORT\_<i>num</i>\_<i>protocol</i>\_ADDR</b><br>
+Container's IP address, e.g. `MYAPP_DB_1_PORT_5432_TCP_ADDR=172.17.0.5`
+
+<b><i>name</i>\_PORT\_<i>num</i>\_<i>protocol</i>\_PORT</b><br>
+Exposed port number, e.g. `MYAPP_DB_1_PORT_5432_TCP_PORT=5432`
+
+<b><i>name</i>\_PORT\_<i>num</i>\_<i>protocol</i>\_PROTO</b><br>
+Protocol (tcp or udp), e.g. `MYAPP_DB_1_PORT_5432_TCP_PROTO=tcp`
+
+<b><i>name</i>\_NAME</b><br>
+Fully qualified container name, e.g. `MYAPP_DB_1_NAME=/myapp_web_1/myapp_db_1`
+
+[Docker links]: http://docs.docker.io/en/latest/use/port_redirection/#linking-a-container
diff --git a/docs/index.md b/docs/index.md
index b0f3b70fb..0b82cc891 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -3,17 +3,17 @@ layout: default
 title: Fig | Punctual, lightweight development environments using Docker
 ---
 
-Fig
-===
+<strong class="strapline">Fast, isolated development environments using Docker.</strong>
 
-<!--
-[![Build Status](https://travis-ci.org/orchardup/fig.png?branch=master)](https://travis-ci.org/orchardup/fig)
-[![PyPI version](https://badge.fury.io/py/fig.png)](http://badge.fury.io/py/fig)
--->
+Define your app's environment with Docker so it can be reproduced anywhere.
 
-Punctual, lightweight development environments using Docker.
+    FROM orchardup/python:2.7
+    ADD . /code
+    RUN pip install -r requirements.txt
+    WORKDIR /code
+    CMD python app.py
 
-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:
+Define your app's services so they can be run alongside in an isolated environment. (No more installing Postgres on your laptop!)
 
 ```yaml
 web:
@@ -37,11 +37,11 @@ There are commands to:
  - tail running services' log output
  - run a one-off command on a service
 
-Fig is a project from [Orchard](https://orchardup.com), a Docker hosting service. [Follow us on Twitter](https://twitter.com/orchardup) to keep up to date with Fig and other Docker news.
+Fig is a project from [Orchard](https://orchardup.com). [Follow us on Twitter](https://twitter.com/orchardup) to keep up to date with Fig and other Docker news.
 
 
-Getting started
----------------
+Quick start
+-----------
 
 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.
 
@@ -156,138 +156,3 @@ If you started Fig with `fig up -d`, you'll probably want to stop your services
     $ 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. If you have any thoughts or suggestions, [open an issue on GitHub](https://github.com/orchardup/fig) or [email us](mailto:hello@orchardup.com).
-
-
-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`.
-
-```yaml
--- 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
-```
-
-### Commands
-
-Most commands are run against one or more services. If the service is omitted, it will apply to all services.
-
-Run `fig [COMMAND] --help` for full usage.
-
-#### build
-
-Build or rebuild services.
-
-Services are built once and then tagged as `project_service`, e.g. `figtest_db`. If you change a service's `Dockerfile` or the contents of its build directory, you can run `fig build` to rebuild it.
-
-#### help
-
-Get help on a command.
-
-#### kill
-
-Force stop service containers.
-
-#### logs
-
-View output from services.
-
-#### ps
-
-List containers.
-
-#### rm
-
-Remove stopped service containers.
-
-
-#### run
-
-Run a one-off command on a service.
-
-For example:
-
-    $ fig run web python manage.py shell
-
-Note that this will not start any services that the command's service links to. So if, for example, your one-off command talks to your database, you will need to run `fig up -d db` first.
-
-#### scale
-
-Set number of containers to run for a service.
-
-Numbers are specified in the form `service=num` as arguments.
-For example:
-
-    $ fig scale web=2 worker=3
-
-#### start
-
-Start existing containers for a service.
-
-#### stop
-
-Stop running containers without removing them. They can be started again with `fig start`.
-
-#### up
-
-Build, (re)create, start and attach to containers for a service.
-
-By default, `fig up` will aggregate the output of each container, and when it exits, all containers will be stopped. If you run `fig up -d`, it'll start the containers in the background and leave them running.
-
-If there are existing containers for a service, `fig up` will stop and recreate them (preserving mounted volumes with [volumes-from]), so that changes in `fig.yml` are picked up.
-
-### 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.
-
-<b><i>name</i>\_PORT</b><br>
-Full URL, e.g. `MYAPP_DB_1_PORT=tcp://172.17.0.5:5432`
-
-<b><i>name</i>\_PORT\_<i>num</i>\_<i>protocol</i></b><br>
-Full URL, e.g. `MYAPP_DB_1_PORT_5432_TCP=tcp://172.17.0.5:5432`
-
-<b><i>name</i>\_PORT\_<i>num</i>\_<i>protocol</i>\_ADDR</b><br>
-Container's IP address, e.g. `MYAPP_DB_1_PORT_5432_TCP_ADDR=172.17.0.5`
-
-<b><i>name</i>\_PORT\_<i>num</i>\_<i>protocol</i>\_PORT</b><br>
-Exposed port number, e.g. `MYAPP_DB_1_PORT_5432_TCP_PORT=5432`
-
-<b><i>name</i>\_PORT\_<i>num</i>\_<i>protocol</i>\_PROTO</b><br>
-Protocol (tcp or udp), e.g. `MYAPP_DB_1_PORT_5432_TCP_PROTO=tcp`
-
-<b><i>name</i>\_NAME</b><br>
-Fully qualified container name, e.g. `MYAPP_DB_1_NAME=/myapp_web_1/myapp_db_1`
-
-
-[Docker links]: http://docs.docker.io/en/latest/use/port_redirection/#linking-a-container
-[volumes-from]: http://docs.docker.io/en/latest/use/working_with_volumes/
diff --git a/docs/install.md b/docs/install.md
new file mode 100644
index 000000000..be0bbe091
--- /dev/null
+++ b/docs/install.md
@@ -0,0 +1,23 @@
+---
+layout: default
+title: Installing Fig
+---
+
+Installing Fig
+==============
+
+First, install Docker. If you're on OS X, you can use [docker-osx](https://github.com/noplay/docker-osx):
+
+    $ curl https://raw.github.com/noplay/docker-osx/master/docker-osx > /usr/local/bin/docker-osx
+    $ chmod +x /usr/local/bin/docker-osx
+    $ docker-osx shell
+
+Docker has guides for [Ubuntu](http://docs.docker.io/en/latest/installation/ubuntulinux/) and [other platforms](http://docs.docker.io/en/latest/installation/) in their documentation.
+
+Next, install Fig:
+
+    $ sudo pip install -U fig
+
+(This command also upgrades Fig when we release a new version. If you don’t have pip installed, try `brew install python` or `apt-get install python-pip`.)
+
+That should be all you need! Run `fig --version` to see if it worked.
diff --git a/docs/rails.md b/docs/rails.md
new file mode 100644
index 000000000..ef33080a2
--- /dev/null
+++ b/docs/rails.md
@@ -0,0 +1,98 @@
+---
+layout: default
+title: Getting started with Fig and Rails
+---
+
+Getting started with Fig and Rails
+==================================
+
+We're going to use Fig to set up and run a Rails/PostgreSQL app. Before starting, you'll need to have [Fig installed](install.html).
+
+Let's set up the three files that'll get us started. First, our app is going to be running inside a Docker container which contains all of its dependencies. We can define what goes inside that Docker container using a file called `Dockerfile`. It'll contain this to start with:
+
+    FROM binaryphile/ruby:2.0.0-p247
+    RUN mkdir /myapp
+    WORKDIR /myapp
+    ADD Gemfile /myapp/Gemfile
+    RUN bundle install
+    ADD . /myapp
+
+That'll put our application code inside an image with Ruby, Bundler and all our dependencies.
+
+Next, we have a bootstrap `Gemfile` which just loads Rails. It'll be overwritten in a moment by `rails new`.
+
+    source 'https://rubygems.org'
+    gem 'rails', '4.0.2'
+
+Finally, `fig.yml` is where the magic happens. It describes what services our app comprises (a database and a web app), how to get each one's Docker image (the database just runs on a pre-made PostgreSQL image, and the web app is built from the current directory), and the configuration we need to link them together and expose the web app's port.
+
+    db:
+      image: orchardup/postgresql
+      ports:
+        - 5432
+    web:
+      build: .
+      command: bundle exec rackup -p 3000
+      volumes:
+        - .:/myapp
+      ports:
+        - 3000:3000
+      links:
+        - db
+
+With those files in place, we can now generate the Rails skeleton app using `fig run`:
+
+    $ fig run web rails new . --force --database=postgresql --skip-bundle
+
+First, Fig will build the image for the `web` service using the `Dockerfile`. Then it'll run `rails new` inside a new container, using that image. Once it's done, you should have a fresh app generated:
+
+    $ ls
+    Dockerfile   app          fig.yml      tmp
+    Gemfile      bin          lib          vendor
+    Gemfile.lock config       log
+    README.rdoc  config.ru    public
+    Rakefile     db           test
+
+Uncomment the line in your new `Gemfile` which loads `therubyracer`, so we've got a Javascript runtime:
+
+    gem 'therubyracer', platforms: :ruby
+
+Now that we've got a new `Gemfile`, we need to build the image again. (This, and changes to the Dockerfile itself, should be the only times you'll need to rebuild).
+
+    $ fig build
+
+The app is now bootable, but we're not quite there yet. By default, Rails expects a database to be running on `localhost` - we need to point it at the `db` container instead. We also need to change the username and password to align with the defaults set by `orchardup/postgresql`.
+
+Open up your newly-generated `database.yml`. Replace its contents with the following:
+
+    development: &default
+      adapter: postgresql
+      encoding: unicode
+      database: myapp_development
+      pool: 5
+      username: docker
+      password: docker
+      host: <%= ENV.fetch('MYAPP_DB_1_PORT_5432_TCP_ADDR', 'localhost') %>
+      port: <%= ENV.fetch('MYAPP_DB_1_PORT_5432_TCP_PORT', '5432') %>
+
+    test:
+      <<: *default
+      database: myapp_test
+
+We can now boot the app.
+
+    $ fig up
+
+If all's well, you should see some PostgreSQL output, and then—after a few seconds—the familiar refrain:
+
+    myapp_web_1 | [2014-01-17 17:16:29] INFO  WEBrick 1.3.1
+    myapp_web_1 | [2014-01-17 17:16:29] INFO  ruby 2.0.0 (2013-11-22) [x86_64-linux-gnu]
+    myapp_web_1 | [2014-01-17 17:16:29] INFO  WEBrick::HTTPServer#start: pid=1 port=3000
+
+Finally, we just need to create the database. In another terminal, run:
+
+    $ fig run web rake db:create
+
+And we're rolling—see for yourself at [localhost:3000](http://localhost:3000) (or [localdocker:3000](http://localdocker:3000) if you're using docker-osx).
+
+![Screenshot of Rails' stock index.html](https://orchardup.com/static/images/fig-rails-screenshot.png)
diff --git a/docs/yml.md b/docs/yml.md
new file mode 100644
index 000000000..2ae3c959a
--- /dev/null
+++ b/docs/yml.md
@@ -0,0 +1,43 @@
+---
+layout: default
+title: fig.yml reference
+---
+
+fig.yml reference
+=================
+
+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`.
+
+```yaml
+-- 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
+```
+
