Merge pull request #1165 from mstanleyjones/tutorial_explain_naming

Update 'usingdocker' tutorial to name the container

engine/tutorials/usingdocker.md

@@ -3,10 +3,6 @@ redirect_from:
 - /engine/userguide/containers/usingdocker/
 description: Learn how to manage and operate Docker containers.
 keywords: docker, the docker guide, documentation, docker.io, monitoring containers, docker top, docker inspect, docker port, ports, docker logs, log, logs
-menu:
-  main:
-    parent: engine_learn_menu
-    weight: -5
 title: Run a simple application
 ---
 
@@ -21,59 +17,68 @@ background. In the process you learned about several Docker commands:
 
 ## Learn about the Docker client
 
-The `docker` program is called the Docker client. Each action you can take with
+The `docker` program is called the Docker client. To control Docker using the
-the client is a command and each command can take a series of flags and arguments.
+client, you use commands, flags, and arguments. Have a look at the following
+example, which uses the `run` command, the `-i` and `-t` flags, and the `ubuntu`
+and `/bin/bash` arguments.
 
-    # Usage:  [sudo] docker [subcommand] [flags] [arguments] ..
+```bash
-    # Example:
+$ docker run -i -t ubuntu /bin/bash
-    $ docker run -i -t ubuntu /bin/bash
+```
 
-You can see this in action by using the `docker version` command to return
+The `docker version` command shows information about the version of Docker the
-version information on the currently installed Docker client and daemon.
+client is using, as well as other version-specific information.
 
-    $ docker version
+```bash
+$ docker version
 
-This command will not only provide you the version of Docker client and
+Client:
-daemon you are using, but also the version of Go (the programming
+ Version:      1.12.5
-language powering Docker).
+ API version:  1.24
+ Go version:   go1.6.4
+ Git commit:   7392c3b
+ Built:        Fri Dec 16 02:42:17 2016
+ OS/Arch:      windows/amd64
 
-    Client:
+Server:
-     Version:      1.12.5
+ Version:      1.12.5
-     API version:  1.24
+ API version:  1.24
-     Go version:   go1.6.4
+ Go version:   go1.6.4
-     Git commit:   7392c3b
+ Git commit:   7392c3b
-     Built:        Fri Dec 16 02:42:17 2016
+ Built:        Fri Dec 16 02:42:17 2016
-     OS/Arch:      windows/amd64
+ OS/Arch:      linux/amd64
-
+```
-    Server:
-     Version:      1.12.5
-     API version:  1.24
-     Go version:   go1.6.4
-     Git commit:   7392c3b
-     Built:        Fri Dec 16 02:42:17 2016
-     OS/Arch:      linux/amd64
 
 ## Get Docker command help
 
-You can display the help for specific Docker commands. The help details the
+Each Docker command has associated usage information, which you can see when you
-options and their usage. To see a list of all the possible commands, use the
+use the `--help` flag. You can use `--help` for the `docker` command itself, or
-following:
+for its sub-commands.
 
-    $ docker --help
+To see usage information for the entire `docker` command, including a list of
+all the possible commands, use `docker --help`.
 
-To see usage for a specific command, specify the command with the `--help` flag:
+```bash
+$ docker --help
+```
 
-    $ docker attach --help
+To see usage for a specific command, add the `--help` flag after that specific
+command. For instance, the following command shows the help text for the
+`docker attach` command.
 
-    Usage: docker attach [OPTIONS] CONTAINER
+```bash
+$ docker attach --help
 
-    Attach to a running container
+Usage: docker attach [OPTIONS] CONTAINER
 
-    Options:
+Attach to a running container
-      --detach-keys string   Override the key sequence for detaching a container
+
-      --help                 Print usage
+Options:
-      --no-stdin             Do not attach STDIN
+  --detach-keys string   Override the key sequence for detaching a container
-      --sig-proxy            Proxy all received signals to the process (default true)
+  --help                 Print usage
+  --no-stdin             Do not attach STDIN
+  --sig-proxy            Proxy all received signals to the process (default true)
+```
 
 > **Note:**
 > For further details and examples of each command, see the
@@ -82,18 +87,20 @@ To see usage for a specific command, specify the command with the `--help` flag:
 ## Run a web application in Docker
 
 Now that you've learned a bit more about the Docker client, you can move onto
-the important stuff: running more containers. So far none of the
+the important stuff: running more containers. First, run an example Python Flask
-containers you've run did anything particularly useful, so you can
+web application as a Docker container.
-change that by running an example web application in Docker.
 
-For the web application you're going to run a Python Flask application.
+```bash
-Start with a `docker run` command.
+$ docker run -d -P --name my_webapp training/webapp python app.py
-
+```
-    $ docker run -d -P training/webapp python app.py
 
 This command consists of the following parts:
 
 * The `-d` flag runs the container in the background (as a so-called daemon).
+* The `--name my_webapp` flag names the container `my_webapp`. If you do not
+  specify a name, Docker creates a random (and sometimes amusing) name for the
+  container. This name is guaranteed to be unique among all the containers
+  running on a given Docker host.
 * The `-P` flag maps any required network ports inside the container to your
   host. This lets you view the web application.
 * The `training/webapp` image is a pre-built image that contains a simple Python
@@ -108,12 +115,14 @@ This command consists of the following parts:
 
 ## View the web application container
 
-Now you can see your running container using the `docker ps` command.
+To see information about your running container, use the `docker ps` command.
 
-    $ docker ps -l
+```bash
+$ docker ps -l
 
-    CONTAINER ID  IMAGE                   COMMAND       CREATED        STATUS        PORTS                    NAMES
+CONTAINER ID  IMAGE                   COMMAND       CREATED        STATUS        PORTS                    NAMES
-    bc533791f3f5  training/webapp:latest  python app.py 5 seconds ago  Up 2 seconds  0.0.0.0:49155->5000/tcp  nostalgic_morse
+bc533791f3f5  training/webapp:latest  python app.py 5 seconds ago  Up 2 seconds  0.0.0.0:49155->5000/tcp  my_webapp
+```
 
 The `-l` flag shows only the details of the *last* container started.
 
@@ -121,30 +130,31 @@ The `-l` flag shows only the details of the *last* container started.
 > By default, the `docker ps` command only shows information about running
 > containers. If you want to see stopped containers too, use the `-a` flag.
 
-You can see the same details you saw [when you first dockerized a
+In particular, have a look at the `PORTS` column.
-container](dockerizing.md), with one important addition in the `PORTS`
-column.
 
-    PORTS
+```none
-    0.0.0.0:49155->5000/tcp
+PORTS
+0.0.0.0:49155->5000/tcp
+```
 
-When you passed the `-P` flag to the `docker run` command,
+When you passed the `-P` flag to the `docker run` command, Docker mapped any
-Docker mapped any ports exposed in the container to your host.
+ports exposed in the container to ports on your host machine. In this case,
+port 5000 (the default port for Python Flask) is mapped to port 49155 on the
+Docker host.
 
 > **Note:**
 > You'll learn more about how to expose ports in Docker images when
 > [you learn how to build images](dockerimages.md).
 
-In this case Docker has exposed port 5000 (the default Python Flask
-port) on port 49155.
-
 Network port bindings are very configurable in Docker. In the last example the
 `-P` flag is a shortcut for `-p 5000` that maps port 5000 inside the container
 to a high port (from *ephemeral port range* which typically ranges from 32768
 to 61000) on the local Docker host. You can also bind Docker containers to
 specific ports using the `-p` flag, for example:
 
-    $ docker run -d -p 80:5000 training/webapp python app.py
+```bash
+$ docker run -d --name my_other_webapp -p 80:5000 training/webapp python app.py
+```
 
 This would map port 5000 inside your container to port 80 on your local
 host. You might be asking about now: why wouldn't we just want to always
@@ -179,9 +189,11 @@ so Docker has a useful shortcut you can use: `docker port`.
 To use `docker port`, specify the ID or name of your container and then
 the port for which you need the corresponding public-facing port.
 
-    $ docker port nostalgic_morse 5000
+```bash
+$ docker port my_webapp 5000
 
-    0.0.0.0:49155
+0.0.0.0:49155
+```
 
 In this case you've looked up what port is mapped externally to port 5000 inside
 the container.
@@ -191,11 +203,13 @@ the container.
 You can also find out a bit more about what's happening with your
 application and use another of the commands you've learned, `docker logs`.
 
-    $ docker logs -f nostalgic_morse
+```basg
+$ docker logs -f my_webapp
 
-    * Running on http://0.0.0.0:5000/
+* Running on http://0.0.0.0:5000/
-    10.0.2.2 - - [06/Nov/2016 20:16:31] "GET / HTTP/1.1" 200 -
+10.0.2.2 - - [06/Nov/2016 20:16:31] "GET / HTTP/1.1" 200 -
-    10.0.2.2 - - [06/Nov/2016 20:16:31] "GET /favicon.ico HTTP/1.1" 404 -
+10.0.2.2 - - [06/Nov/2016 20:16:31] "GET /favicon.ico HTTP/1.1" 404 -
+```
 
 The `-f` flag causes the `docker logs` command to act like the `tail -f` command
 and watch the container's standard output. You can see here the logs from Flask
@@ -206,10 +220,12 @@ showing the application running on port 5000 and the access log entries for it.
 In addition to the container's logs you can also examine the processes
 running inside it using the `docker top` command.
 
-    $ docker top nostalgic_morse
+```bash
+$ docker top my_webapp
 
-    PID                 USER                COMMAND
+PID                 USER                COMMAND
-    854                 root                python app.py
+854                 root                python app.py
+```
 
 Here you can see that the `python app.py` command is the only process
 running inside the container.
@@ -220,45 +236,56 @@ Lastly, you can take a low-level dive into the Docker container using the
 `docker inspect` command. It returns a JSON document containing useful
 configuration and status information for the specified container.
 
-    $ docker inspect nostalgic_morse
+```bash
+$ docker inspect my_webapp
+```
 
 You can see a sample of that JSON output.
 
-    [{
+```none
-        "ID": "bc533791f3f500b280a9626688bc79e342e3ea0d528efe3a86a51ecb28ea20",
+[{
-        "Created": "2014-05-26T05:52:40.808952951Z",
+    "ID": "bc533791f3f500b280a9626688bc79e342e3ea0d528efe3a86a51ecb28ea20",
-        "Path": "python",
+    "Created": "2014-05-26T05:52:40.808952951Z",
-        "Args": [
+    "Path": "python",
-           "app.py"
+    "Args": [
-        ],
+       "app.py"
-        "Config": {
+    ],
-           "Hostname": "bc533791f3f5",
+    "Config": {
-           "Domainname": "",
+       "Hostname": "bc533791f3f5",
-           "User": "",
+       "Domainname": "",
-    . . .
+       "User": "",
+  ...
+}]
+```
 
 You can also narrow down the information you want to return by requesting a
 specific element, for example to return the container's IP address, you would:
 
-    {% raw %}
+```bash
-    $ docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' nostalgic_morse
+{% raw %}
-    {% endraw %}
+$ docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' my_webapp
 
-    172.17.0.5
+172.17.0.5
+{% endraw %}
+```
 
 ## Stop the web application container
 
 The web application is still running inside the container. You can stop it using
-the `docker stop` command and the name of the container: `nostalgic_morse`.
+the `docker stop` command and the name of the container: `my_webapp`.
 
-    $ docker stop nostalgic_morse
+```bash
+$ docker stop my_webapp
 
-    nostalgic_morse
+my_webapp
+```
 
 You can now use the `docker ps` command to check if the container has
 been stopped.
 
-    $ docker ps -l
+```bash
+$ docker ps -l
+```
 
 ## Restart the web application container
 
@@ -267,41 +294,47 @@ developer needs the container back. From here you have two choices: you
 can create a new container or restart the old one. Look at
 starting your previous container back up.
 
-    $ docker start nostalgic_morse
+```bash
+$ docker start my_webapp
 
-    nostalgic_morse
+my_webapp
+```
 
 Now quickly run `docker ps -l` again to see the running container is
 back up or browse to the container's URL to see if the application
 responds.
 
 > **Note:**
-> Also available is the `docker restart` command that runs a stop and
+> The `docker restart` command is also available. It is the equivalent of
-> then start on the container.
+> running `docker stop` followed by `docker start`.
 
 ## Remove the web application container
 
 Your colleague has let you know that they've now finished with the container
 and won't need it again. Now, you can remove it using the `docker rm` command.
 
-    $ docker rm nostalgic_morse
+```bash
+$ docker rm my_webapp
 
-    Error: Impossible to remove a running container, please stop it first or use -f
+Error: Impossible to remove a running container, please stop it first or use -f
-    2014/05/24 08:12:56 Error: failed to remove one or more containers
+2014/05/24 08:12:56 Error: failed to remove one or more containers
+```
 
 What happened? You can't actually remove a running container. This protects
 you from accidentally removing a running container you might need. You can try
 this again by stopping the container first.
 
-    $ docker stop nostalgic_morse
+```bash
+$ docker stop my_webapp
 
-    nostalgic_morse
+my_webapp
 
-    $ docker rm nostalgic_morse
+$ docker rm my_webapp
 
-    nostalgic_morse
+my_webapp
+```
 
-And now the container is stopped and deleted.
+Now the container is stopped and deleted.
 
 > **Note:**
 > Always remember that removing a container is final!