diff --git a/README.md b/README.md
index 9f90c18..1dd0e76 100644
--- a/README.md
+++ b/README.md
@@ -2,12 +2,7 @@
Baseimage-docker is a special [Docker](http://www.docker.io) image that is configured for correct use within Docker containers. It is Ubuntu, plus modifications for Docker-friendliness. You can use it as a base for your own Docker images.
-Baseimage-docker is available for pulling from on [the Docker registry](https://index.docker.io/u/phusion/baseimage/)!
-
- * **Github**: https://github.com/phusion/baseimage-docker
- * **Discussion forum**: https://groups.google.com/d/forum/passenger-docker
- * **Twitter**: https://twitter.com/phusion_nl
- * **Blog**: http://blog.phusion.nl/
+Baseimage-docker is available for pulling from [the Docker registry](https://index.docker.io/u/phusion/baseimage/)!
### What are the problems with the stock Ubuntu base image?
@@ -15,6 +10,7 @@ Ubuntu is not designed to be run inside docker. Its init system, Upstart, assume
Baseimage-docker gets everything right. The "Contents" section describes all the things that it modifies.
+
### Why use baseimage-docker?
You can configure the stock `ubuntu` image yourself from your Dockerfile, so why bother using baseimage-docker?
@@ -24,7 +20,36 @@ You can configure the stock `ubuntu` image yourself from your Dockerfile, so why
* It reduces the time needed to run `docker build`, allowing you to iterate your Dockerfile more quickly.
* It reduces download time during redeploys. Docker only needs to download the base image once: during the first deploy. On every subsequent deploys, only the changes you make on top of the base image are downloaded.
-## Contents
+-----------------------------------------
+
+**Related resources**:
+ [Github](https://github.com/phusion/baseimage-docker) |
+ [Docker registry](https://index.docker.io/u/phusion/baseimage/) |
+ [Discussion forum](https://groups.google.com/d/forum/passenger-docker) |
+ [Twitter](https://twitter.com/phusion_nl) |
+ [Blog](http://blog.phusion.nl/)
+
+**Table of contents**
+
+ * [What's inside the image?](#whats_inside)
+ * [Overview](#whats_inside_overview)
+ * [Wait, I thought Docker is about running a single process in a container?](#docker_single_process)
+ * [Inspecting baseimage-docker](#inspecting)
+ * [Using baseimage-docker as base image](#using)
+ * [Getting started](#getting_started)
+ * [Adding additional daemons](#adding_additional_daemons)
+ * [Running scripts during container startup](#running_startup_scripts)
+ * [Login to the container](#login)
+ * [Building the image yourself](#building)
+ * [Conclusion](#conclusion)
+
+-----------------------------------------
+
+
+## What's inside the image?
+
+
+### Overview
*Looking for a more complete base image, one that is ideal for Ruby, Python, Node.js and Meteor web apps? Take a look at [passenger-docker](https://github.com/phusion/passenger-docker).*
@@ -41,12 +66,14 @@ You can configure the stock `ubuntu` image yourself from your Dockerfile, so why
Baseimage-docker is very lightweight: it only consumes 6 MB of memory.
+
### Wait, I thought Docker is about running a single process in a container?
Absolutely not true. Docker runs fine with multiple processes in a container. In fact, there is no technical reason why you should limit yourself to one process - it only makes things harder for you and breaks all kinds of essential system functionality, e.g. syslog.
Baseimage-docker *encourages* multiple processes through the use of runit.
+
## Inspecting baseimage-docker
To look around in the image, run:
@@ -55,8 +82,12 @@ To look around in the image, run:
You don't have to download anything manually. The above command will automatically pull the baseimage-docker image from the Docker registry.
+
## Using baseimage-docker as base image
+
+### Getting started
+
The image is called `phusion/baseimage`, and is available on the Docker registry.
By default, it allows SSH access for the key in `image/insecure_key`. This makes it easy for you to login to the container, but you should replace this key as soon as possible.
@@ -86,6 +117,7 @@ By default, it allows SSH access for the key in `image/insecure_key`. This makes
# Clean up APT when done.
RUN apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
+
### Adding additional daemons
You can add additional daemons to the image by creating runit entries. You only have to write a small shell script which runs your daemon, and runit will keep it up and running for you, restarting it when it crashes, etc.
@@ -106,6 +138,7 @@ Here's an example showing you how to a memached server runit entry can be made.
Note that the shell script must run the daemon **without letting it daemonize/fork it**. Usually, daemons provide a command line flag or a config file option for that.
+
### Running scripts during container startup
The baseimage-docker init system, `/sbin/my_init`, runs the following scripts during startup, in the following order:
@@ -125,6 +158,7 @@ The following example shows how you can add a startup script. This script simply
RUN mkdir -p /etc/my_init.d
ADD logtime.sh /etc/my_init.d/logtime.sh
+
### Login to the container
You can use SSH to login to any container that is based on baseimage-docker.
@@ -145,6 +179,7 @@ Now SSH into the container. In this example we're using [the default insecure ke
ssh -i insecure_key root@
+
## Building the image yourself
If for whatever reason you want to build the image yourself instead of downloading it from the Docker registry, follow these instructions.
@@ -168,6 +203,7 @@ If you want to call the resulting image something else, pass the NAME variable,
make build NAME=joe/baseimage
+
## Conclusion
* Using baseimage-docker? [Tweet about us](https://twitter.com/share) or [follow us on Twitter](https://twitter.com/phusion_nl).