Merge pull request #787 from gasi/nodejs-centos-docs

* Documentation: Deploying a Node.js Web App on CentOS
* Documentation: small formatting improvements

docs/Makefile

@@ -6,6 +6,7 @@ SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = _build
+PYTHON        = python
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
@@ -38,6 +39,7 @@ help:
 #	@echo "  linkcheck  to check all external links for integrity"
 #	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 	@echo "  docs       to build the docs and copy the static files to the outputdir"
+	@echo "  server     to serve the docs in your browser under \`http://localhost:8000\`"
 	@echo "  publish    to publish the app to dotcloud"
 
 clean:
@@ -49,6 +51,8 @@ docs:
 	@echo
 	@echo "Build finished. The documentation pages are now in $(BUILDDIR)/html."
 
+server:
+	@cd $(BUILDDIR)/html; $(PYTHON) -m SimpleHTTPServer 8000
 
 site:
 	cp -r website $(BUILDDIR)/

docs/README.md

@@ -14,20 +14,22 @@ Installation
 ------------
 
 * Work in your own fork of the code, we accept pull requests.
-* Install sphinx: ``pip install sphinx``
-* Install sphinx httpdomain contrib package ``sphinxcontrib-httpdomain``
+* Install sphinx: `pip install sphinx`
+    * Mac OS X: `[sudo] pip-2.7 install sphinx`)
+* Install sphinx httpdomain contrib package: `pip install sphinxcontrib-httpdomain`
+    * Mac OS X: `[sudo] pip-2.7 install sphinxcontrib-httpdomain`
 * If pip is not available you can probably install it using your favorite package manager as **python-pip**
 
 Usage
 -----
-* change the .rst files with your favorite editor to your liking
-* run *make docs* to clean up old files and generate new ones
-* your static website can now be found in the _build dir
-* to preview what you have generated, cd into _build/html and then run 'python -m SimpleHTTPServer 8000'
+* Change the `.rst` files with your favorite editor to your liking.
+* Run `make docs` to clean up old files and generate new ones.
+* Your static website can now be found in the `_build` directory.
+* To preview what you have generated run `make server` and open <http://localhost:8000/> in your favorite browser.
 
-Working using github's file editor
+Working using GitHub's file editor
 ----------------------------------
-Alternatively, for small changes and typo's you might want to use github's built in file editor. It allows
+Alternatively, for small changes and typo's you might want to use GitHub's built in file editor. It allows
 you to preview your changes right online. Just be carefull not to create many commits.
 
 Images
@@ -72,4 +74,4 @@ Guides on using sphinx
 
 * Code examples
 
-  Start without $, so it's easy to copy and paste.
+  Start without $, so it's easy to copy and paste.

docs/sources/api/index.rst

@@ -2,8 +2,8 @@
 :description: docker documentation
 :keywords: docker, ipa, documentation
 
-API's
-=============
+APIs
+====
 
 This following :
 

docs/sources/concepts/introduction.rst

@@ -5,8 +5,8 @@
 Introduction
 ============
 
-Docker - The Linux container runtime
-------------------------------------
+Docker -- The Linux container runtime
+-------------------------------------
 
 Docker complements LXC with a high-level API which operates at the process level. It runs unix processes with strong guarantees of isolation and repeatability across servers.
 

docs/sources/contributing/devenvironment.rst

@@ -1,8 +1,8 @@
-:title: Setting up a dev environment
+:title: Setting Up a Dev Environment
 :description: Guides on how to contribute to docker
 :keywords: Docker, documentation, developers, contributing, dev environment
 
-Setting up a dev environment
+Setting Up a Dev Environment
 ============================
 
 Instructions that have been verified to work on Ubuntu 12.10,

docs/sources/examples/couchdb_data_volumes.rst

@@ -4,8 +4,8 @@
 
 .. _running_couchdb_service:
 
-Create a CouchDB service
-========================
+CouchDB Service
+===============
 
 .. include:: example_header.inc
 

docs/sources/examples/index.rst

@@ -1,6 +1,6 @@
 :title: Docker Examples
 :description: Examples on how to use Docker
-:keywords: docker, hello world, examples
+:keywords: docker, hello world, node, nodejs, python, couch, couchdb, redis, ssh, sshd, examples
 
 
 
@@ -16,6 +16,7 @@ Contents:
    hello_world
    hello_world_daemon
    python_web_app
+   nodejs_web_app
    running_redis_service
    running_ssh_service
    couchdb_data_volumes

docs/sources/examples/nodejs_web_app.rst

@@ -0,0 +1,236 @@
+:title: Running a Node.js app on CentOS
+:description: Installing and running a Node.js app on CentOS
+:keywords: docker, example, package installation, node, centos
+
+.. _nodejs_web_app:
+
+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 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.
+
+Create Node.js app
+++++++++++++++++++
+
+First, create a ``package.json`` file that describes your app and its
+dependencies:
+
+.. code-block:: json
+
+    {
+      "name": "docker-centos-hello",
+      "private": true,
+      "version": "0.0.1",
+      "description": "Node.js Hello World app on CentOS using docker",
+      "author": "Daniel Gasienica <daniel@gasienica.ch>",
+      "dependencies": {
+        "express": "3.2.4"
+      }
+    }
+
+Then, create an ``index.js`` file that defines a web app using the
+`Express.js <http://expressjs.com/>`_ framework:
+
+.. code-block:: javascript
+
+    var express = require('express');
+
+    // Constants
+    var PORT = 8080;
+
+    // App
+    var app = express();
+    app.get('/', function (req, res) {
+      res.send('Hello World\n');
+    });
+
+    app.listen(PORT)
+    console.log('Running on http://localhost:' + PORT);
+
+
+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.
+
+Creating a ``Dockerfile``
++++++++++++++++++++++++++
+
+Create an empty file called ``Dockerfile``:
+
+.. code-block:: bash
+
+    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):
+
+.. code-block:: bash
+
+    # DOCKER-VERSION 0.3.4
+
+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`_:
+
+.. code-block:: bash
+
+    FROM    centos:6.4
+
+Since we’re building a Node.js app, you’ll have to install Node.js as well as
+npm on your CentOS image. Node.js is required to run your app and npm to install
+your app’s dependencies defined in ``package.json``.
+To install the right package for CentOS, we’ll use the instructions from the
+`Node.js wiki`_:
+
+.. code-block:: bash
+
+    # Enable EPEL for Node.js
+    RUN     rpm -Uvh http://download.fedoraproject.org/pub/epel/6/i386/epel-release-6-8.noarch.rpm
+    # Install Node.js and npm
+    RUN     yum install -y npm-1.2.17-5.el6
+
+To bundle your app’s source code inside the docker image, use the ``ADD``
+command:
+
+.. code-block:: bash
+
+    # Bundle app source
+    ADD . /src
+
+Install your app dependencies using npm:
+
+.. 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:
+
+.. code-block:: bash
+
+    EXPOSE  8080
+
+Last but not least, define the command to run your app using ``CMD`` which
+defines your runtime, i.e. ``node``, and the path to our app, i.e.
+``src/index.js`` (see the step where we added the source to the container):
+
+.. code-block:: bash
+
+    CMD ["node", "/src/index.js"]
+
+Your ``Dockerfile`` should now look like this:
+
+.. code-block:: bash
+
+
+    # DOCKER-VERSION 0.3.4
+    FROM    centos:6.4
+
+    # Enable EPEL for Node.js
+    RUN     rpm -Uvh http://download.fedoraproject.org/pub/epel/6/i386/epel-release-6-8.noarch.rpm
+    # Install Node.js and npm
+    RUN     yum install -y npm-1.2.17-5.el6
+
+    # Bundle app source
+    ADD . /src
+    # Install app dependencies
+    RUN cd /src; npm install
+
+    EXPOSE  8080
+    CMD ["node", "/src/index.js"]
+
+
+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 image so it’s easier
+to find later using the ``docker images`` command:
+
+.. code-block:: bash
+
+    docker build -t <your username>/centos-node-hello .
+
+Your image will now be listed by docker:
+
+.. code-block:: bash
+
+    docker images
+
+    > # Example
+    > REPOSITORY                 TAG       ID              CREATED
+    > centos                     6.4       539c0211cd76    8 weeks ago
+    > gasi/centos-node-hello     latest    d64d3505b0d2    2 hours ago
+
+
+Run the image
++++++++++++++
+
+Running your image with ``-d`` runs the container in detached mode, leaving the
+container running in the background. Run the image you previously built:
+
+.. code-block:: bash
+
+    docker run -d <your username>/centos-node-hello
+
+Print the output of your app:
+
+.. code-block:: bash
+
+    # Get container ID
+    docker ps
+
+    # Print app output
+    docker logs <container id>
+
+    > # Example
+    > Running on http://localhost:8080
+
+
+Test
+++++
+
+To test your app, get the the port of your app that docker mapped:
+
+.. code-block:: bash
+
+    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
+``49160``.
+
+Now you can call your app using ``curl`` (install if needed via:
+``sudo apt-get install curl``):
+
+.. code-block:: bash
+
+    curl -i localhost:49160
+
+    > HTTP/1.1 200 OK
+    > X-Powered-By: Express
+    > Content-Type: text/html; charset=utf-8
+    > Content-Length: 12
+    > Date: Sun, 02 Jun 2013 03:53:22 GMT
+    > Connection: keep-alive
+    >
+    > 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
+https://github.com/gasi/docker-node-hello.
+
+Continue to :ref:`running_redis_service`.
+
+
+.. _Node.js wiki: https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager#rhelcentosscientific-linux-6
+.. _docker index: https://index.docker.io/

docs/sources/examples/python_web_app.rst

@@ -4,8 +4,8 @@
 
 .. _python_web_app:
 
-Building a python web app
-=========================
+Python Web App
+==============
 
 .. include:: example_header.inc
 

docs/sources/examples/running_examples.rst

@@ -4,7 +4,7 @@
 
 .. _running_examples:
 
-Running The Examples
+Running the Examples
 --------------------
 
 All the examples assume your machine is running the docker daemon. To run the docker daemon in the background, simply type:

docs/sources/examples/running_redis_service.rst

@@ -4,8 +4,8 @@
 
 .. _running_redis_service:
 
-Create a redis service
-======================
+Redis Service
+=============
 
 .. include:: example_header.inc
 

docs/sources/examples/running_ssh_service.rst

@@ -4,8 +4,8 @@
 
 .. _running_ssh_service:
 
-Create an ssh daemon service
-============================
+SSH Daemon Service
+==================
 
 .. include:: example_header.inc
 

docs/sources/index.rst

@@ -7,8 +7,8 @@
 Introduction
 ============
 
-Docker - The Linux container runtime
-------------------------------------
+Docker -- The Linux container runtime
+-------------------------------------
 
 Docker complements LXC with a high-level API which operates at the process level. It runs unix processes with strong guarantees of isolation and repeatability across servers.
 

docs/sources/use/basics.rst

@@ -3,8 +3,8 @@
 :keywords: Examples, Usage, basic commands, docker, documentation, examples
 
 
-The basics
-=============
+The Basics
+==========
 
 Starting Docker
 ---------------

docs/sources/use/workingwithrepository.rst

@@ -4,8 +4,8 @@
 
 .. _working_with_the_repository:
 
-Working with the repository
-============================
+Working with the Repository
+===========================
 
 
 Top-level repositories and user repositories
@@ -14,9 +14,9 @@ Top-level repositories and user repositories
 Generally, there are two types of repositories: Top-level repositories which are controlled by the people behind
 Docker, and user repositories.
 
-* Top-level repositories can easily be recognized by not having a / (slash) in their name. These repositories can
+* Top-level repositories can easily be recognized by not having a ``/`` (slash) in their name. These repositories can
   generally be trusted.
-* User repositories always come in the form of <username>/<repo_name>. This is what your published images will look like.
+* User repositories always come in the form of ``<username>/<repo_name>``. This is what your published images will look like.
 * User images are not checked, it is therefore up to you whether or not you trust the creator of this image.