paulczar fixes plus example file

Signed-off-by: Patrick Chanezon <patlist@chanezon.com>

docs/index.md

@@ -15,34 +15,28 @@ recommend that you use it in production yet.
 
 Using Compose is basically a three-step process.
 
-First, you define your app's environment with a `Dockerfile` so it can be
-reproduced anywhere:
-
-```Dockerfile
-FROM python:2.7
-WORKDIR /code
-ADD requirements.txt /code/
-RUN pip install -r requirements.txt
-ADD . /code
-CMD python app.py
-```
-
-Next, you define the services that make up your app in `docker-compose.yml` so
+1. Define your app's environment with a `Dockerfile` so it can be
+reproduced anywhere.
+2. Define the services that make up your app in `docker-compose.yml` so
 they can be run together in an isolated environment:
+3. Lastly, run `docker-compose up` and Compose will start and run your entire app.
+
+A `docker-compose.yml` looks like this:
 
 ```yaml
 web:
   build: .
-  links:
-   - db
+  command: python app.py
   ports:
-   - "8000:8000"
-db:
-  image: postgres
+   - "5000:5000"
+  volumes:
+   - .:/code
+  links:
+   - redis
+redis:
+  image: redis
 ```
 
-Lastly, run `docker-compose up` and Compose will start and run your entire app.
-
 Compose has commands for managing the whole lifecycle of your application:
 
  * Start, stop and rebuild services
@@ -108,13 +102,18 @@ specify how to build the image using a file called
     ADD . /code
     WORKDIR /code
     RUN pip install -r requirements.txt
+    CMD python app.py
 
-This tells Docker to include Python, your code, and your Python dependencies in
-a Docker image. For more information on how to write Dockerfiles, see the
-[Docker user
-guide](https://docs.docker.com/userguide/dockerimages/#building-an-image-from-a-dockerfile)
-and the
-[Dockerfile reference](http://docs.docker.com/reference/builder/).
+This tells Docker to:
+
+* Build an image starting with the Python 2.7 image.
+* Add the curret directory `.` into the path `/code` in the image.
+* Set the working directory to `/code`.
+* Install your Python dependencies. 
+
+For more information on how to write Dockerfiles, see the [Docker user guide](https://docs.docker.com/userguide/dockerimages/#building-an-image-from-a-dockerfile) and the [Dockerfile reference](http://docs.docker.com/reference/builder/).
+
+You can test that this builds by running `docker build -t web .`.
 
 ### Define services
 
@@ -134,19 +133,21 @@ Next, define a set of services using `docker-compose.yml`:
 
 This defines two services:
 
- - `web`, which is built from the `Dockerfile` in the current directory. It also
-   says to run the command `python app.py` inside the image, 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
-   [redis](https://registry.hub.docker.com/_/redis/), which gets pulled from the
-   Docker Hub registry.
+#### web
+
+* Builds from the `Dockerfile` in the current directory. 
+* Defines to run the command `python app.py` inside the image on start.
+* Forwards the exposed port 5000 on the container to port 5000 on the host machine.
+* Connects the web container to the Redis service via a link. 
+* Mounts the current directory on the host to `/code` inside the container allowing you to modify the code without having to rebuild the image.
+
+#### redis
+
+* Uses the public [redis](https://registry.hub.docker.com/_/redis/) image which gets pulled from the Docker Hub registry.
 
 ### Build and run your app with Compose
 
-Now, when you run `docker-compose up`, Compose will pull a Redis image, build an
-image for your code, and start everything up:
+Now, when you run `docker-compose up`, Compose will pull a Redis image, build an image for your code, and start everything up:
 
     $ docker-compose up
     Pulling image redis...
@@ -157,7 +158,12 @@ image for your code, and start everything up:
     web_1   |  * Running on http://0.0.0.0:5000/
 
 The web app should now be listening on port 5000 on your Docker daemon host (if
-you're using Boot2docker, `boot2docker ip` will tell you its address).
+you're using Boot2docker, `boot2docker ip` will tell you its address). In a browser,
+open `http://ip-from-boot2docker:5000` and you should get a message in your browser saying:
+
+`Hello World! I have been seen 1 times.`
+
+Refreshing the page will see the number increment.
 
 If you want to run your services in the background, you can pass the `-d` flag
 (for daemon mode) to `docker-compose up` and use `docker-compose ps` to see what