update to description of files generated from examples, which are no longer owned by root w/new release

updated descriptions of changing file ownership and images per Seb's comments

fixed line wraps

fixed line breaks per Joffrey's comments

Signed-off-by: Victoria Bialas <[email protected]>

docs/Dockerfile

@@ -10,6 +10,7 @@ RUN svn checkout https://github.com/docker/kitematic/trunk/docs /docs/content/ki
 RUN svn checkout https://github.com/docker/toolbox/trunk/docs /docs/content/toolbox
 RUN svn checkout https://github.com/docker/opensource/trunk/docs /docs/content/project
 
+
 ENV PROJECT=compose
 # To get the git info for this repo
 COPY . /src

docs/django.md

@@ -117,12 +117,23 @@ In this step, you create a Django started project by building the image from the
         -rwxr-xr-x 1 root   root   manage.py
         -rw-rw-r-- 1 user   user   requirements.txt
 
-    The files `django-admin` created are owned by root. This happens because
-    the container runs as the `root` user.
+  If you are running Docker on Linux, the files `django-admin` created are owned
+  by root. This happens because the container runs as the root user. Change the
+  ownership of the the new files.
 
-4. Change the ownership of the new files.
+          sudo chown -R $USER:$USER .
 
-        sudo chown -R $USER:$USER .
+  If you are running Docker on Mac or Windows, you should already have ownership
+  of all files, including those generated by `django-admin`. List the files just
+  verify this.
+
+        $ ls -l
+        total 32
+        -rw-r--r--  1 user  staff  145 Feb 13 23:00 Dockerfile
+        drwxr-xr-x  6 user  staff  204 Feb 13 23:07 composeexample
+        -rw-r--r--  1 user  staff  159 Feb 13 23:02 docker-compose.yml
+        -rwxr-xr-x  1 user  staff  257 Feb 13 23:07 manage.py
+        -rw-r--r--  1 user  staff   16 Feb 13 23:01 requirements.txt
 
 
 ## Connect the database
@@ -169,6 +180,8 @@ In this section, you set up the database connection for Django.
     Docker host. If you are using a Docker Machine VM, you can use the
     `docker-machine ip MACHINE_NAME` to get the IP address.
 
+    ![Django example](images/django-it-worked.png)
+
 ## More Compose documentation
 
 - [User guide](index.md)

docs/overview.md

@@ -24,11 +24,14 @@ CI workflows. You can learn more about each case in
 
 Using Compose is basically a three-step process.
 
-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.
+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:
 
@@ -37,16 +40,16 @@ A `docker-compose.yml` looks like this:
       web:
         build: .
         ports:
-         - "5000:5000"
+        - "5000:5000"
         volumes:
-         - .:/code
-         - logvolume01:/var/log
+        - .:/code
+        - logvolume01:/var/log
         links:
-         - redis
-      redis:
-        image: redis
-    volumes:
-      logvolume01: {}
+        - redis
+        redis:
+          image: redis
+        volumes:
+          logvolume01: {}
 
 For more information about the Compose file, see the
 [Compose file reference](compose-file.md)
@@ -80,14 +83,12 @@ The features of Compose that make it effective are:
 
 ### Multiple isolated environments on a single host
 
-Compose uses a project name to isolate environments from each other. You can use
-this project name to:
+Compose uses a project name to isolate environments from each other. You can make use of this project name in several different contexts:
 
-* on a dev host, to create multiple copies of a single environment (ex: you want
-  to run a stable copy for each feature branch of a project)
+* on a dev host, to create multiple copies of a single environment (e.g., you want to run a stable copy for each feature branch of a project)
 * on a CI server, to keep builds from interfering with each other, you can set
   the project name to a unique build number
-* on a shared host or dev host, to prevent different projects which may use the
+* on a shared host or dev host, to prevent different projects, which may use the
   same service names, from interfering with each other
 
 The default project name is the basename of the project directory. You can set
@@ -148,9 +149,7 @@ started guide" to a single machine readable Compose file and a few commands.
 An important part of any Continuous Deployment or Continuous Integration process
 is the automated test suite. Automated end-to-end testing requires an
 environment in which to run tests. Compose provides a convenient way to create
-and destroy isolated testing environments for your test suite. By defining the full
-environment in a [Compose file](compose-file.md) you can create and destroy these
-environments in just a few commands:
+and destroy isolated testing environments for your test suite. By defining the full environment in a [Compose file](compose-file.md) you can create and destroy these environments in just a few commands:
 
     $ docker-compose up -d
     $ ./run_tests
@@ -159,9 +158,7 @@ environments in just a few commands:
 ### Single host deployments
 
 Compose has traditionally been focused on development and testing workflows,
-but with each release we're making progress on more production-oriented features.
-You can use Compose to deploy to a remote Docker Engine. The Docker Engine may
-be a single instance provisioned with
+but with each release we're making progress on more production-oriented features. You can use Compose to deploy to a remote Docker Engine. The Docker Engine may be a single instance provisioned with
 [Docker Machine](https://docs.docker.com/machine/) or an entire
 [Docker Swarm](https://docs.docker.com/swarm/) cluster.
 

docs/rails.md

@@ -30,7 +30,9 @@ Dockerfile consists of:
     RUN bundle install
     ADD . /myapp
 
-That'll put your application code inside an image that will build a container with Ruby, Bundler and all your dependencies inside it. For more information on how to write Dockerfiles, see the [Docker user guide](https://docs.docker.com/engine/userguide/dockerimages/#building-an-image-from-a-dockerfile) and the [Dockerfile reference](https://docs.docker.com/engine/reference/builder/).
+That'll put your application code inside an image that will build a container
+with Ruby, Bundler and all your dependencies inside it. For more information on
+how to write Dockerfiles, see the [Docker user guide](https://docs.docker.com/engine/userguide/dockerimages/#building-an-image-from-a-dockerfile) and the [Dockerfile reference](https://docs.docker.com/engine/reference/builder/).
 
 Next, create a bootstrap `Gemfile` which just loads Rails. It'll be overwritten in a moment by `rails new`.
 
@@ -41,7 +43,11 @@ You'll need an empty `Gemfile.lock` in order to build our `Dockerfile`.
 
     $ touch Gemfile.lock
 
-Finally, `docker-compose.yml` is where the magic happens. This file describes the services that comprise your app (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 needed to link them together and expose the web app's port.
+Finally, `docker-compose.yml` is where the magic happens. This file describes
+the services that comprise your app (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 needed
+to link them together and expose the web app's port.
 
     db:
       image: postgres
@@ -62,22 +68,38 @@ using `docker-compose run`:
 
     $ docker-compose run web rails new . --force --database=postgresql --skip-bundle
 
-First, Compose 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 generated a fresh app:
-
-    $ ls
-    Dockerfile   app          docker-compose.yml      tmp
-    Gemfile      bin          lib          vendor
-    Gemfile.lock config       log
-    README.rdoc  config.ru    public
-    Rakefile     db           test
-
-
-The files `rails new` created are owned by root. This happens because the
-container runs as the `root` user.  Change the ownership of the new files.
-
-    sudo chown -R $USER:$USER .
+First, Compose 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 generated a fresh app:
+
+      $ ls -l
+      total 56
+      -rw-r--r--   1 user  staff   215 Feb 13 23:33 Dockerfile
+      -rw-r--r--   1 user  staff  1480 Feb 13 23:43 Gemfile
+      -rw-r--r--   1 user  staff  2535 Feb 13 23:43 Gemfile.lock
+      -rw-r--r--   1 root  root   478 Feb 13 23:43 README.rdoc
+      -rw-r--r--   1 root  root   249 Feb 13 23:43 Rakefile
+      drwxr-xr-x   8 root  root   272 Feb 13 23:43 app
+      drwxr-xr-x   6 root  root   204 Feb 13 23:43 bin
+      drwxr-xr-x  11 root  root   374 Feb 13 23:43 config
+      -rw-r--r--   1 root  root   153 Feb 13 23:43 config.ru
+      drwxr-xr-x   3 root  root   102 Feb 13 23:43 db
+      -rw-r--r--   1 user  staff   161 Feb 13 23:35 docker-compose.yml
+      drwxr-xr-x   4 root  root   136 Feb 13 23:43 lib
+      drwxr-xr-x   3 root  root   102 Feb 13 23:43 log
+      drwxr-xr-x   7 root  root   238 Feb 13 23:43 public
+      drwxr-xr-x   9 root  root   306 Feb 13 23:43 test
+      drwxr-xr-x   3 root  root   102 Feb 13 23:43 tmp
+      drwxr-xr-x   3 root  root   102 Feb 13 23:43 vendor
+
+
+If you are running Docker on Linux, the files `rails new`  created are owned by
+root. This happens because the container runs as the root user. Change the
+ownership of the the new files.
+
+      sudo chown -R $USER:$USER .
+
+If you are running Docker on Mac or Windows, you should already have ownership
+of all files, including those generated by `rails new`. List the files just to
+verify this.
 
 Uncomment the line in your new `Gemfile` which loads `therubyracer`, so you've
 got a Javascript runtime:
@@ -130,6 +152,14 @@ Finally, you need to create the database. In another terminal, run:
 
 That's it. Your app should now be running on port 3000 on your Docker daemon. If you're using [Docker Machine](https://docs.docker.com/machine/), then `docker-machine ip MACHINE_VM` returns the Docker host IP address.
 
+![Rails example](images/rails-welcome.png)
+
+>**Note**: If you stop the example application and attempt to restart it, you might get the
+following error: `web_1 | A server is already running. Check
+/myapp/tmp/pids/server.pid.` One way to resolve this is to delete the file
+`tmp/pids/server.pid`, and then re-start the application with `docker-compose
+up`.
+
 
 ## More Compose documentation