updated/improved Compose samples (docker#3438)

* updated/improved Compose samples

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

* linked some more basic docker-compose commands

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

* coypedit

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

Author: londoncalling

compose/django.md

@@ -61,21 +61,24 @@ and a `docker-compose.yml` file. (You can use either a `.yml` or `.yaml` extensi
     expose. See the [`docker-compose.yml` reference](compose-file.md) for more
     information on how this file works.
 
-9. Add the following configuration to the file.
-
-        version: '2'
-        services:
-          db:
-            image: postgres
-          web:
-            build: .
-            command: python3 manage.py runserver 0.0.0.0:8000
-            volumes:
-              - .:/code
-            ports:
-              - "8000:8000"
-            depends_on:
-              - db
+9.  Add the following configuration to the file.
+
+    ```none
+    version: '3'
+
+    services:
+      db:
+        image: postgres
+      web:
+        build: .
+        command: python3 manage.py runserver 0.0.0.0:8000
+        volumes:
+          - .:/code
+        ports:
+          - "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
-  by root. This happens because the container runs as the root user. Change the
-  ownership of the new files.
+    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 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 `django-admin`. List the files just
-  verify this.
+    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 to verify this.
 
         $ ls -l
         total 32
@@ -133,9 +137,9 @@ In this step, you create a Django starter project by building the image from the
 
 In this section, you set up the database connection for Django.
 
-1. In your project directory, edit the `composeexample/settings.py` file.
+1.  In your project directory, edit the `composeexample/settings.py` file.
 
-2. Replace the `DATABASES = ...` with the following:
+2.  Replace the `DATABASES = ...` with the following:
 
         DATABASES = {
             'default': {
@@ -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.
-
-        $ docker-compose up
-        Starting composepractice_db_1...
-        Starting composepractice_web_1...
-        Attaching to composepractice_db_1, composepractice_web_1
-        ...
-        db_1  | PostgreSQL init process complete; ready for start up.
-        ...
-        db_1  | LOG:  database system is ready to accept connections
-        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
-    Docker host. If you are using a Docker Machine VM, you can use the
-    `docker-machine ip MACHINE_NAME` to get the IP address.
+3.  Save and close the file.
+
+4.  Run the [docker-compose up](/compose/reference/up/) command from the top level directory for your project.
+
+    ```none
+    $ docker-compose up
+    djangosample_db_1 is up-to-date
+    Creating djangosample_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".
+
+    . . .
+
+    web_1  | May 30, 2017 - 21:44:49
+    web_1  | Django version 1.11.1, 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 Docker host. On Docker for Mac and Docker for Windows, go
+    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:**
-> 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
-> purposes, you may 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)
-> for more information.
-
-5. Clean up: Shut down containers with CONTROL-C.
-
-  ```
-  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.
+    > Note:
+    >
+    > On certain platforms (Windows 10), you might need 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)  for more information.
+     {: .note-vanilla}
+
+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
+      ```
+
+    * 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/images/django-it-worked.png

@@ -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.
-You can use the same terminal window in which you started the database, or
-another one where you have access to a command prompt. This is a clean way to
-stop the application.
+To stop the application, run [docker-compose down](/compose/reference/down/) in
+your project directory. You can use the same terminal window in which you
+started the database, or another one where you have access to a command prompt.
+This is a clean way to stop the application.
 
 ```none
 vmb at snapair in ~/sandbox/rails

compose/rails.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
-containers, as shown in the example below.
+This runs [docker-compose up](/compose/reference/up/) in detached mode, pulls
+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,
-but preserves your Wordpress database.
+The command [docker-compose down](/compose/reference/down/) removes the
+containers and default network, but preserves your Wordpress database.
 
 The command `docker-compose down --volumes` removes the containers, default
 network, and the Wordpress database.