Merge pull request #2534 from jamtur01/examples_fixes

A variety of syntax and style fixes for the Docker examples

docs/sources/examples/couchdb_data_volumes.rst

@@ -10,7 +10,7 @@ CouchDB Service
 .. include:: example_header.inc
 
 Here's an example of using data volumes to share the same data between
-2 CouchDB containers.  This could be used for hot upgrades, testing
+two CouchDB containers.  This could be used for hot upgrades, testing
 different versions of CouchDB on the same data, etc.
 
 Create first database
@@ -25,8 +25,8 @@ Note that we're marking ``/var/lib/couchdb`` as a data volume.
 Add data to the first database
 ------------------------------
 
-We're assuming your docker host is reachable at `localhost`. If not,
-replace `localhost` with the public IP of your docker host.
+We're assuming your Docker host is reachable at ``localhost``. If not,
+replace ``localhost`` with the public IP of your Docker host.
 
 .. code-block:: bash
 
@@ -37,7 +37,7 @@ replace `localhost` with the public IP of your docker host.
 Create second database
 ----------------------
 
-This time, we're requesting shared access to $COUCH1's volumes.
+This time, we're requesting shared access to ``$COUCH1``'s volumes.
 
 .. code-block:: bash
 
@@ -52,5 +52,5 @@ Browse data on the second database
     URL="http://$HOST:$(sudo docker port $COUCH2 5984)/_utils/"
     echo "Navigate to $URL in your browser. You should see the same data as in the first database"'!'
 
-Congratulations, you are running 2 Couchdb containers, completely
+Congratulations, you are now running two Couchdb containers, completely
 isolated from each other *except* for their data.

docs/sources/examples/hello_world.rst

@@ -12,16 +12,16 @@ Hello World
 Running the Examples
 ====================
 
-All the examples assume your machine is running the docker daemon. To
-run the docker daemon in the background, simply type:
+All the examples assume your machine is running the ``docker`` daemon. To
+run the ``docker`` daemon in the background, simply type:
 
 .. code-block:: bash
 
    sudo docker -d &
 
-Now you can run docker in client mode: by default all commands will be
+Now you can run Docker in client mode: by default all commands will be
 forwarded to the ``docker`` daemon via a protected Unix socket, so you
-must run as root.
+must run as the ``root`` or via the ``sudo`` command.
 
 .. code-block:: bash
 
@@ -38,23 +38,24 @@ Hello World
 
 This is the most basic example available for using Docker.
 
-Download the base image (named "ubuntu"):
+Download the base image which is named ``ubuntu``:
 
 .. code-block:: bash
 
     # Download an ubuntu image
     sudo docker pull ubuntu
 
-Alternatively to the *ubuntu* image, you can select *busybox*, a bare
+Alternatively to the ``ubuntu`` image, you can select ``busybox``, a bare
 minimal Linux system. The images are retrieved from the Docker
 repository.
 
 
 .. code-block:: bash
 
-    #run a simple echo command, that will echo hello world back to the console over standard out.
     sudo docker run ubuntu /bin/echo hello world
 
+This command will run a simple ``echo`` command, that will echo ``hello world`` back to the console over standard out.
+
 **Explanation:**
 
 - **"sudo"** execute the following commands as user *root* 
@@ -100,9 +101,9 @@ we stop it.
     CONTAINER_ID=$(sudo docker run -d ubuntu /bin/sh -c "while true; do echo hello world; sleep 1; done")
 
 We are going to run a simple hello world daemon in a new container
-made from the *ubuntu* image.
+made from the ``ubuntu`` image.
 
-- **"docker run -d "** run a command in a new container. We pass "-d"
+- **"sudo docker run -d "** run a command in a new container. We pass "-d"
   so it runs as a daemon.
 - **"ubuntu"** is the image we want to run the command inside of.
 - **"/bin/sh -c"** is the command we want to run in the container

docs/sources/examples/index.rst

@@ -10,7 +10,7 @@ Examples
 
 Here are some examples of how to use Docker to create running
 processes, starting from a very simple *Hello World* and progressing
-to more substantial services like you might find in production.
+to more substantial services like those which you might find in production.
 
 .. toctree::
    :maxdepth: 1

docs/sources/examples/mongodb.rst

@@ -10,8 +10,8 @@ Building an Image with MongoDB
 .. include:: example_header.inc
 
 The goal of this example is to show how you can build your own
-docker images with MongoDB preinstalled. We will do that by
-constructing a Dockerfile that downloads a base image, adds an
+Docker images with MongoDB pre-installed. We will do that by
+constructing a ``Dockerfile`` that downloads a base image, adds an
 apt source and installs the database software on Ubuntu.
 
 Creating a ``Dockerfile``
@@ -41,7 +41,7 @@ Since we want to be running the latest version of MongoDB we'll need to add the
     RUN echo 'deb http://downloads-distro.mongodb.org/repo/ubuntu-upstart dist 10gen' | tee /etc/apt/sources.list.d/10gen.list
 
 Then, we don't want Ubuntu to complain about init not being available so we'll
-divert /sbin/initctl to /bin/true so it thinks everything is working.
+divert ``/sbin/initctl`` to ``/bin/true`` so it thinks everything is working.
 
 .. code-block:: bash
 
@@ -65,8 +65,8 @@ run without needing to provide a special configuration file)
     # Create the MongoDB data directory
     RUN mkdir -p /data/db
 
-Finally, we'll expose the standard port that MongoDB runs on (27107) as well as
-define an ENTRYPOINT for the container.
+Finally, we'll expose the standard port that MongoDB runs on, 27107, as well as
+define an ``ENTRYPOINT`` instruction for the container.
 
 .. code-block:: bash
 
@@ -78,7 +78,7 @@ run all of the commands.
 
 .. code-block:: bash
 
-    docker build -t <yourname>/mongodb .
+    sudo docker build -t <yourname>/mongodb .
 
 Now you should be able to run ``mongod`` as a daemon and be able to connect on
 the local port!
@@ -86,13 +86,13 @@ the local port!
 .. code-block:: bash
 
     # Regular style
-    MONGO_ID=$(docker run -d <yourname>/mongodb)
+    MONGO_ID=$(sudo docker run -d <yourname>/mongodb)
 
     # Lean and mean
-    MONGO_ID=$(docker run -d <yourname>/mongodb --noprealloc --smallfiles)
+    MONGO_ID=$(sudo docker run -d <yourname>/mongodb --noprealloc --smallfiles)
 
     # Check the logs out
-    docker logs $MONGO_ID
+    sudo docker logs $MONGO_ID
 
     # Connect and play around
     mongo --port <port you get from `docker ps`>

docs/sources/examples/nodejs_web_app.rst

@@ -10,7 +10,7 @@ Node.js Web App
 .. include:: example_header.inc
 
 The goal of this example is to show you how you can build your own
-docker images from a parent image using a ``Dockerfile`` . We will do
+Docker images from a parent image using a ``Dockerfile`` . We will do
 that by making a simple Node.js hello world web application running on
 CentOS. You can get the full source code at
 https://github.com/gasi/docker-node-hello.
@@ -55,7 +55,7 @@ Then, create an ``index.js`` file that defines a web app using the
 
 
 In the next steps, we’ll look at how you can run this app inside a CentOS
-container using docker. First, you’ll need to build a docker image of your app.
+container using Docker. First, you’ll need to build a Docker image of your app.
 
 Creating a ``Dockerfile``
 +++++++++++++++++++++++++
@@ -67,8 +67,8 @@ Create an empty file called ``Dockerfile``:
     touch Dockerfile
 
 Open the ``Dockerfile`` in your favorite text editor and add the following line
-that defines the version of docker the image requires to build
-(this example uses docker 0.3.4):
+that defines the version of Docker the image requires to build
+(this example uses Docker 0.3.4):
 
 .. code-block:: bash
 
@@ -76,7 +76,7 @@ that defines the version of docker the image requires to build
 
 Next, define the parent image you want to use to build your own image on top of.
 Here, we’ll use `CentOS <https://index.docker.io/_/centos/>`_ (tag: ``6.4``)
-available on the `docker index`_:
+available on the `Docker index`_:
 
 .. code-block:: bash
 
@@ -95,23 +95,23 @@ To install the right package for CentOS, we’ll use the instructions from the
     # Install Node.js and npm
     RUN     yum install -y npm
 
-To bundle your app’s source code inside the docker image, use the ``ADD``
-command:
+To bundle your app’s source code inside the Docker image, use the ``ADD``
+instruction:
 
 .. code-block:: bash
 
     # Bundle app source
     ADD . /src
 
-Install your app dependencies using npm:
+Install your app dependencies using the ``npm`` binary:
 
 .. code-block:: bash
 
     # Install app dependencies
     RUN cd /src; npm install
 
-Your app binds to port ``8080`` so you’ll use the ``EXPOSE`` command
-to have it mapped by the docker daemon:
+Your app binds to port ``8080`` so you’ll use the ``EXPOSE`` instruction
+to have it mapped by the ``docker`` daemon:
 
 .. code-block:: bash
 
@@ -152,7 +152,7 @@ Building your image
 +++++++++++++++++++
 
 Go to the directory that has your ``Dockerfile`` and run the following
-command to build a docker image. The ``-t`` flag let’s you tag your
+command to build a Docker image. The ``-t`` flag let’s you tag your
 image so it’s easier to find later using the ``docker images``
 command:
 
@@ -160,7 +160,7 @@ command:
 
     sudo docker build -t <your username>/centos-node-hello .
 
-Your image will now be listed by docker:
+Your image will now be listed by Docker:
 
 .. code-block:: bash
 
@@ -199,17 +199,17 @@ Print the output of your app:
 Test
 ++++
 
-To test your app, get the the port of your app that docker mapped:
+To test your app, get the the port of your app that Docker mapped:
 
 .. code-block:: bash
 
-    docker ps
+    sudo docker ps
 
     > # Example
     > ID            IMAGE                          COMMAND              ...   PORTS
     > ecce33b30ebf  gasi/centos-node-hello:latest  node /src/index.js         49160->8080
 
-In the example above, docker mapped the ``8080`` port of the container to
+In the example above, Docker mapped the ``8080`` port of the container to
 ``49160``.
 
 Now you can call your app using ``curl`` (install if needed via:
@@ -229,7 +229,7 @@ Now you can call your app using ``curl`` (install if needed via:
     > Hello World
 
 We hope this tutorial helped you get up and running with Node.js and
-CentOS on docker. You can get the full source code at
+CentOS on Docker. You can get the full source code at
 https://github.com/gasi/docker-node-hello.
 
 Continue to :ref:`running_redis_service`.

docs/sources/examples/postgresql_service.rst

@@ -13,7 +13,7 @@ PostgreSQL Service
 
 .. note::
 
-    As of version 0.5.2, docker requires root privileges to run.
+    As of version 0.5.2, Docker requires root privileges to run.
     You have to either manually adjust your system configuration (permissions on
     /var/run/docker.sock or sudo config), or prefix `docker` with `sudo`. Check
     `this thread`_ for details.
@@ -24,8 +24,7 @@ PostgreSQL Service
 Installing PostgreSQL on Docker
 -------------------------------
 
-For clarity I won't be showing commands output.
-
+For clarity I won't be showing command output.
 
 Run an interactive shell in Docker container.
 
@@ -62,7 +61,7 @@ Finally, install PostgreSQL 9.2
 
 Now, create a PostgreSQL superuser role that can create databases and
 other roles.  Following Vagrant's convention the role will be named
-`docker` with `docker` password assigned to it.
+``docker`` with ``docker`` password assigned to it.
 
 .. code-block:: bash
 
@@ -108,7 +107,7 @@ Bash prompt; you can also locate it using ``docker ps -a``.
 
 .. code-block:: bash
 
-    docker commit <container_id> <your username>/postgresql
+    sudo docker commit <container_id> <your username>/postgresql
 
 Finally, run PostgreSQL server via ``docker``.
 

docs/sources/examples/python_web_app.rst

@@ -10,9 +10,9 @@ Python Web App
 .. include:: example_header.inc
 
 The goal of this example is to show you how you can author your own
-docker images using a parent image, making changes to it, and then
+Docker images using a parent image, making changes to it, and then
 saving the results as a new image. We will do that by making a simple
-hello flask web application image.
+hello Flask web application image.
 
 **Steps:**
 
@@ -20,22 +20,22 @@ hello flask web application image.
 
     sudo docker pull shykes/pybuilder
 
-We are downloading the "shykes/pybuilder" docker image
+We are downloading the ``shykes/pybuilder`` Docker image
 
 .. code-block:: bash
 
     URL=http://github.com/shykes/helloflask/archive/master.tar.gz
 
-We set a URL variable that points to a tarball of a simple helloflask web app
+We set a ``URL`` variable that points to a tarball of a simple helloflask web app
 
 .. code-block:: bash
 
     BUILD_JOB=$(sudo docker run -d -t shykes/pybuilder:latest /usr/local/bin/buildapp $URL)
 
-Inside of the "shykes/pybuilder" image there is a command called
-buildapp, we are running that command and passing the $URL variable
+Inside of the ``shykes/pybuilder`` image there is a command called
+``buildapp``, we are running that command and passing the ``$URL`` variable
 from step 2 to it, and running the whole thing inside of a new
-container. BUILD_JOB will be set with the new container_id.
+container. The ``BUILD_JOB`` environment variable will be set with the new container ID.
 
 .. code-block:: bash
 
@@ -43,13 +43,13 @@ container. BUILD_JOB will be set with the new container_id.
     [...]
 
 While this container is running, we can attach to the new container to
-see what is going on. Ctrl-C to disconnect.
+see what is going on. You can use Ctrl-C to disconnect.
 
 .. code-block:: bash
 
     sudo docker ps -a
-    
-List all docker containers. If this container has already finished
+
+List all Docker containers. If this container has already finished
 running, it will still be listed here.
 
 .. code-block:: bash
@@ -57,8 +57,8 @@ running, it will still be listed here.
     BUILD_IMG=$(sudo docker commit $BUILD_JOB _/builds/github.com/shykes/helloflask/master)
 
 Save the changes we just made in the container to a new image called
-``_/builds/github.com/hykes/helloflask/master`` and save the image id in
-the BUILD_IMG variable name.
+``_/builds/github.com/hykes/helloflask/master`` and save the image ID in
+the ``BUILD_IMG`` variable name.
 
 .. code-block:: bash
 
@@ -72,24 +72,24 @@ the BUILD_IMG variable name.
 - **/usr/local/bin/runapp** is the command which starts the web app.
 
 Use the new image we just created and create a new container with
-network port 5000, and return the container id and store in the
-WEB_WORKER variable.
+network port 5000, and return the container ID and store in the
+``WEB_WORKER`` variable.
 
 .. code-block:: bash
 
     sudo docker logs $WEB_WORKER
      * Running on http://0.0.0.0:5000/
 
-View the logs for the new container using the WEB_WORKER variable, and
-if everything worked as planned you should see the line "Running on
-http://0.0.0.0:5000/" in the log output.
+View the logs for the new container using the ``WEB_WORKER`` variable, and
+if everything worked as planned you should see the line ``Running on
+http://0.0.0.0:5000/`` in the log output.
 
 .. code-block:: bash
 
     WEB_PORT=$(sudo docker port $WEB_WORKER 5000)
 
 Look up the public-facing port which is NAT-ed. Find the private port
-used by the container and store it inside of the WEB_PORT variable.
+used by the container and store it inside of the ``WEB_PORT`` variable.
 
 .. code-block:: bash
 
@@ -97,8 +97,8 @@ used by the container and store it inside of the WEB_PORT variable.
     curl http://127.0.0.1:$WEB_PORT
       Hello world!
 
-Access the web app using curl. If everything worked as planned you
-should see the line "Hello world!" inside of your console.
+Access the web app using the ``curl`` binary. If everything worked as planned you
+should see the line ``Hello world!`` inside of your console.
 
 **Video:**
 

docs/sources/examples/running_redis_service.rst

@@ -9,7 +9,7 @@ Redis Service
 
 .. include:: example_header.inc
 
-Very simple, no frills, redis service.
+Very simple, no frills, Redis service.
 
 Open a docker container
 -----------------------
@@ -35,13 +35,13 @@ Snapshot the installation
 
 .. code-block:: bash
 
-    docker ps -a  # grab the container id (this will be the first one in the list)
-    docker commit <container_id> <your username>/redis
+    sudo docker ps -a  # grab the container id (this will be the first one in the list)
+    sudo docker commit <container_id> <your username>/redis
 
 Run the service
 ---------------
 
-Running the service with `-d` runs the container in detached mode, leaving the
+Running the service with ``-d`` runs the container in detached mode, leaving the
 container running in the background. Use your snapshot.
 
 .. code-block:: bash
@@ -51,7 +51,7 @@ container running in the background. Use your snapshot.
 Test 1
 ++++++
 
-Connect to the container with the redis-cli.
+Connect to the container with the ``redis-cli`` binary.
 
 .. code-block:: bash
 
@@ -67,7 +67,7 @@ Connect to the container with the redis-cli.
 Test 2
 ++++++
 
-Connect to the host os with the redis-cli.
+Connect to the host os with the ``redis-cli`` binary.
 
 .. code-block:: bash
 

docs/sources/examples/running_riak_service.rst

@@ -107,7 +107,7 @@ Create a ``supervisord`` configuration file
 +++++++++++++++++++++++++++++++++++++++++++
 
 Create an empty file called ``supervisord.conf``. Make sure it's at the same
-level as your ``Dockerfile``:
+directory level as your ``Dockerfile``:
 
 .. code-block:: bash
 

docs/sources/examples/running_ssh_service.rst

@@ -12,14 +12,14 @@ SSH Daemon Service
 
 **Video:**
 
-I've create a little screencast to show how to create a sshd service
+I've create a little screencast to show how to create a SSHd service
 and connect to it. It is something like 11 minutes and not entirely
 smooth, but gives you a good idea.
 
 .. note::
-   This screencast was created before ``docker`` version 0.5.2, so the
+   This screencast was created before Docker version 0.5.2, so the
    daemon is unprotected and available via a TCP port. When you run
-   through the same steps in a newer version of ``docker``, you will
+   through the same steps in a newer version of Docker, you will
    need to add ``sudo`` in front of each ``docker`` command in order
    to reach the daemon over its protected Unix socket.
 
@@ -29,13 +29,14 @@ smooth, but gives you a good idea.
       <iframe width="800" height="400" src="http://ascii.io/a/2637/raw" frameborder="0"></iframe>
     </div>
         
-You can also get this sshd container by using
-::
+You can also get this sshd container by using:
+
+.. code-block:: bash
 
     sudo docker pull dhrp/sshd
 
 
-The password is 'screencast'
+The password is ``screencast``.
 
 **Video's Transcription:**