From 1cb4557cc8e40f509898bded6684a45070fbb2a4 Mon Sep 17 00:00:00 2001 From: James Turnbull Date: Sat, 2 Nov 2013 18:26:52 -0700 Subject: [PATCH] A variety of syntax and style fixes for the Docker examples * Made Docker a proper noun when needed. * Fixed code syntax * Fixed some whitespace issues * Fixed some typos and grammar * Tidied up some examples --- .../sources/examples/couchdb_data_volumes.rst | 10 ++--- docs/sources/examples/hello_world.rst | 19 ++++----- docs/sources/examples/index.rst | 2 +- docs/sources/examples/mongodb.rst | 18 ++++----- docs/sources/examples/nodejs_web_app.rst | 32 +++++++-------- docs/sources/examples/postgresql_service.rst | 9 ++--- docs/sources/examples/python_web_app.rst | 40 +++++++++---------- .../examples/running_redis_service.rst | 12 +++--- .../sources/examples/running_riak_service.rst | 2 +- docs/sources/examples/running_ssh_service.rst | 13 +++--- 10 files changed, 79 insertions(+), 78 deletions(-) diff --git a/docs/sources/examples/couchdb_data_volumes.rst b/docs/sources/examples/couchdb_data_volumes.rst index 7296a3eea1..60674fe9a0 100644 --- a/docs/sources/examples/couchdb_data_volumes.rst +++ b/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. diff --git a/docs/sources/examples/hello_world.rst b/docs/sources/examples/hello_world.rst index 54ebdacc6a..6d6c1b28a6 100644 --- a/docs/sources/examples/hello_world.rst +++ b/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 diff --git a/docs/sources/examples/index.rst b/docs/sources/examples/index.rst index 74a7e7c406..6167e35652 100644 --- a/docs/sources/examples/index.rst +++ b/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 diff --git a/docs/sources/examples/mongodb.rst b/docs/sources/examples/mongodb.rst index 5527fc00c7..3e37d74c30 100644 --- a/docs/sources/examples/mongodb.rst +++ b/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 /mongodb . + sudo docker build -t /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 /mongodb) + MONGO_ID=$(sudo docker run -d /mongodb) # Lean and mean - MONGO_ID=$(docker run -d /mongodb --noprealloc --smallfiles) + MONGO_ID=$(sudo docker run -d /mongodb --noprealloc --smallfiles) # Check the logs out - docker logs $MONGO_ID + sudo docker logs $MONGO_ID # Connect and play around mongo --port diff --git a/docs/sources/examples/nodejs_web_app.rst b/docs/sources/examples/nodejs_web_app.rst index 67584d1794..19b10f6cbb 100644 --- a/docs/sources/examples/nodejs_web_app.rst +++ b/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 `_ (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 /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`. diff --git a/docs/sources/examples/postgresql_service.rst b/docs/sources/examples/postgresql_service.rst index 35bcc01b95..3649775485 100644 --- a/docs/sources/examples/postgresql_service.rst +++ b/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 /postgresql + sudo docker commit /postgresql Finally, run PostgreSQL server via ``docker``. diff --git a/docs/sources/examples/python_web_app.rst b/docs/sources/examples/python_web_app.rst index 8654ab5f19..c707fcdec6 100644 --- a/docs/sources/examples/python_web_app.rst +++ b/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:** diff --git a/docs/sources/examples/running_redis_service.rst b/docs/sources/examples/running_redis_service.rst index 2305980de7..ac869501b0 100644 --- a/docs/sources/examples/running_redis_service.rst +++ b/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 /redis + sudo docker ps -a # grab the container id (this will be the first one in the list) + sudo docker commit /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 diff --git a/docs/sources/examples/running_riak_service.rst b/docs/sources/examples/running_riak_service.rst index d98de6a77c..ae08a4b7f0 100644 --- a/docs/sources/examples/running_riak_service.rst +++ b/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 diff --git a/docs/sources/examples/running_ssh_service.rst b/docs/sources/examples/running_ssh_service.rst index db3a71c961..59a80fbf6e 100644 --- a/docs/sources/examples/running_ssh_service.rst +++ b/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. -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:**