updated/improved Compose samples (#3438)

* updated/improved Compose samples

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

* linked some more basic docker-compose commands

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

* coypedit

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

compose/django.md

@@ -63,7 +63,9 @@ and a `docker-compose.yml` file. (You can use either a `.yml` or `.yaml` extensi
 
 9.  Add the following configuration to the file.
 
-        version: '2'
+    ```none
+    version: '3'
+
     services:
       db:
         image: postgres
@@ -76,6 +78,7 @@ and a `docker-compose.yml` file. (You can use either a `.yml` or `.yaml` extensi
           - "8000:8000"
         depends_on:
           - db
+    ```
 
     This file defines two services: The `db` service and the `web` service.
 
@@ -87,7 +90,8 @@ In this step, you create a Django starter project by building the image from the
 
 1. Change to the root of your project directory.
 
-2. Create the Django project using the `docker-compose` command.
+2. Create the Django project by running
+the [docker-compose run](/compose/reference/run/) command as follows.
 
         docker-compose run web django-admin.py startproject composeexample .
 
@@ -110,15 +114,15 @@ In this step, you create a Django starter project by building the image from the
         -rwxr-xr-x 1 root   root   manage.py
         -rw-rw-r-- 1 user   user   requirements.txt
 
-  If you are running Docker on Linux, the files `django-admin` created are owned
+    If you are running Docker on Linux, the files `django-admin` created are
-  by root. This happens because the container runs as the root user. Change the
+    owned by root. This happens because the container runs as the root user.
-  ownership of the new files.
+    Change the ownership of the new files.
 
           sudo chown -R $USER:$USER .
 
-  If you are running Docker on Mac or Windows, you should already have ownership
+    If you are running Docker on Mac or Windows, you should already
-  of all files, including those generated by `django-admin`. List the files just
+    have ownership of all files, including those generated by
-  verify this.
+    `django-admin`. List the files just to verify this.
 
         $ ls -l
         total 32
@@ -148,53 +152,92 @@ In this section, you set up the database connection for Django.
         }
 
     These settings are determined by the
-    [postgres](https://hub.docker.com/_/postgres/) Docker image
+    [postgres](https://store.docker.com/images/postgres) Docker image
     specified in `docker-compose.yml`.
 
 3.  Save and close the file.
 
-4. Run the `docker-compose up` command.
+4.  Run the [docker-compose up](/compose/reference/up/) command from the top level directory for your project.
 
+    ```none
     $ docker-compose up
-        Starting composepractice_db_1...
+    djangosample_db_1 is up-to-date
-        Starting composepractice_web_1...
+    Creating djangosample_web_1 ...
-        Attaching to composepractice_db_1, composepractice_web_1
+    Creating djangosample_web_1 ... done
+    Attaching to djangosample_db_1, djangosample_web_1
+    db_1   | The files belonging to this database system will be owned by user "postgres".
+    db_1   | This user must also own the server process.
+    db_1   |
+    db_1   | The database cluster will be initialized with locale "en_US.utf8".
+    db_1   | The default database encoding has accordingly been set to "UTF8".
+    db_1   | The default text search configuration will be set to "english".
+
     . . .
-        db_1  | PostgreSQL init process complete; ready for start up.
+
-        ...
+    web_1  | May 30, 2017 - 21:44:49
-        db_1  | LOG:  database system is ready to accept connections
+    web_1  | Django version 1.11.1, using settings 'composeexample.settings'
-        db_1  | LOG:  autovacuum launcher started
-        ..
-        web_1 | Django version 1.8.4, using settings 'composeexample.settings'
     web_1  | Starting development server at http://0.0.0.0:8000/
     web_1  | Quit the server with CONTROL-C.
+    ```
 
-    At this point, your Django app should be running at port `8000` on your
+    At this point, your Django app should be running at port `8000` on
-    Docker host. If you are using a Docker Machine VM, you can use the
+    your Docker host. On Docker for Mac and Docker for Windows, go
-    `docker-machine ip MACHINE_NAME` to get the IP address.
+    to `http://localhost:8000` on a web browser to see the Django
+    welcome page. If you are using [Docker Machine](/machine/overview.md),
+    then `docker-machine ip MACHINE_VM` returns the Docker host IP
+    address, to which you can append the port (`<Docker-Host-IP>:8000`).
 
     ![Django example](images/django-it-worked.png)
 
-> **Note:**
+    > Note:
-> On certain platforms (Windows 10), you may additionally need to edit `ALLOWED_HOSTS`
+    >
-> inside settings.py and add your Docker hostname or IP to the list.  For demo
+    > On certain platforms (Windows 10), you might need to
-> purposes, you may set the value to:
+      edit `ALLOWED_HOSTS` inside `settings.py` and add your Docker host name
+      or IP address to the list.  For demo purposes, you can set the value to:
     >
     >       ALLOWED_HOSTS = ['*']
     >
     > Please note this value is **not** safe for production usage.  Refer to the
-> [Django documentation](https://docs.djangoproject.com/en/1.11/ref/settings/#allowed-hosts)
+     [Django documentation](https://docs.djangoproject.com/en/1.11/ref/settings/#allowed-hosts)  for more information.
-> for more information.
+     {: .note-vanilla}
 
-5. Clean up: Shut down containers with CONTROL-C.
+5.  List running containers.
+
+    In another terminal window, list the running Docker processes with the `docker ps` command.
+
+    ```none
+    $ docker ps
+CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                    NAMES
+def85eff5f51        django_web          "python3 manage.py..."   10 minutes ago      Up 9 minutes        0.0.0.0:8000->8000/tcp   django_web_1
+678ce61c79cc        postgres            "docker-entrypoint..."   20 minutes ago      Up 9 minutes        5432/tcp                 django_db_1
 
     ```
+
+6.  Shut down services and clean up by using either of these methods:
+
+    * Stop the application by typing `Ctrl-C`
+    in the same shell in where you started it:
+
+      ```none
       Gracefully stopping... (press Ctrl+C again to force)
       Killing test_web_1 ... done
       Killing test_db_1 ... done
       ```
 
-  It's safe to `rm -rf` your project directory.
+    * Or, for a more elegant shutdown, switch to a different shell, and run [docker-compose down](/compose/reference/down/) from the top level of your Django sample project directory.
+
+      ```none
+      vmb at mymachine in ~/sandbox/django
+      $ docker-compose down
+      Stopping django_web_1 ... done
+      Stopping django_db_1 ... done
+      Removing django_web_1 ... done
+      Removing django_web_run_1 ... done
+      Removing django_db_1 ... done
+      Removing network django_default
+      ```
+
+  Once you've shut down the app, you can safely remove the Django project directory (for example, `rm -rf django`).
 
 ## More Compose documentation
 

compose/rails.md

@@ -66,7 +66,7 @@ to link them together and expose the web app's port.
 ### Build the project
 
 With those four files in place, you can now generate the Rails skeleton app
-using `docker-compose run`:
+using [docker-compose run](/compose/reference/run/):
 
     docker-compose run web rails new . --force --database=postgresql
 
@@ -139,7 +139,7 @@ test:
 
 You can now boot the app with:
 
-    docker-compose up
+    [docker-compose up](/compose/reference/up/)
 
 If all's well, you should see some PostgreSQL output, and then—after a few
 seconds—the familiar refrain:
@@ -178,10 +178,10 @@ Docker host IP address, to which you can append the port
 
 ### Stop the application
 
-To stop the application, run `docker-compose down` in your project directory.
+To stop the application, run [docker-compose down](/compose/reference/down/) in
-You can use the same terminal window in which you started the database, or
+your project directory. You can use the same terminal window in which you
-another one where you have access to a command prompt. This is a clean way to
+started the database, or another one where you have access to a command prompt.
-stop the application.
+This is a clean way to stop the application.
 
 ```none
 vmb at snapair in ~/sandbox/rails

compose/wordpress.md

@@ -34,7 +34,7 @@ Compose to set up and run WordPress. Before starting, you'll need to have
     mount for data persistence:
 
     ```none
-    version: '2'
+    version: '3'
 
     services:
        db:
@@ -75,8 +75,9 @@ Compose to set up and run WordPress. Before starting, you'll need to have
 
 Now, run `docker-compose up -d` from your project directory.
 
-This pulls the needed images, and starts the wordpress and database
+This runs [docker-compose up](/compose/reference/up/) in detached mode, pulls
-containers, as shown in the example below.
+the needed images, and starts the wordpress and database containers, as shown in
+the example below.
 
     $ docker-compose up -d
     Creating network "my_wordpress_default" with the default driver
@@ -127,8 +128,8 @@ browser.
 
 ### Shutdown and Cleanup
 
-The command `docker-compose down` removes the containers and default network,
+The command [docker-compose down](/compose/reference/down/) removes the
-but preserves your Wordpress database.
+containers and default network, but preserves your Wordpress database.
 
 The command `docker-compose down --volumes` removes the containers, default
 network, and the Wordpress database.