From b4df0b17afef027e88f0536cbfc9518e04f62eec Mon Sep 17 00:00:00 2001 From: Daniel Gasienica Date: Sat, 1 Jun 2013 21:25:51 -0700 Subject: [PATCH 01/12] Add `make server` command to preview docs --- docs/Makefile | 4 ++++ docs/README.md | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/Makefile b/docs/Makefile index 26168b6f38..dcbf111c29 100644 --- a/docs/Makefile +++ b/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)/ diff --git a/docs/README.md b/docs/README.md index e1ca45b085..ef24c3fb1d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -23,7 +23,7 @@ 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' +* to preview what you have generated run `make server` and open in your favorite browser. Working using github's file editor ---------------------------------- From 3ca9c11110ff5068fd453a3e8aa0b39ee26d363c Mon Sep 17 00:00:00 2001 From: Daniel Gasienica Date: Sat, 1 Jun 2013 21:26:18 -0700 Subject: [PATCH 02/12] Add Mac OS X instructions for doc tools --- docs/README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/README.md b/docs/README.md index ef24c3fb1d..54588e995d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -14,8 +14,10 @@ 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 From 01ce63aacdd975130244f4be70bc90736e85d457 Mon Sep 17 00:00:00 2001 From: Daniel Gasienica Date: Sat, 1 Jun 2013 21:26:54 -0700 Subject: [PATCH 03/12] Make style consistent --- docs/README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/README.md b/docs/README.md index 54588e995d..74ab2bd0cd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -22,14 +22,14 @@ Installation 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 run `make server` and open in your favorite browser. +* 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 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 @@ -74,4 +74,4 @@ Guides on using sphinx * Code examples - Start without $, so it's easy to copy and paste. \ No newline at end of file + Start without $, so it's easy to copy and paste. From e3fd61ad74521b1a94502cf8dcc7c450f035c168 Mon Sep 17 00:00:00 2001 From: Daniel Gasienica Date: Sat, 1 Jun 2013 21:27:27 -0700 Subject: [PATCH 04/12] Add more tags --- docs/sources/examples/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/examples/index.rst b/docs/sources/examples/index.rst index 7eb2ecbe94..3a8e01fe03 100644 --- a/docs/sources/examples/index.rst +++ b/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, python, couch, couchdb, redis, ssh, sshd, examples From f6f345b1fe0ecc1adba449b0078d96388dd48892 Mon Sep 17 00:00:00 2001 From: Daniel Gasienica Date: Sat, 1 Jun 2013 21:55:01 -0700 Subject: [PATCH 05/12] Fix typo --- docs/sources/api/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sources/api/index.rst b/docs/sources/api/index.rst index 4d8ff3fe67..85770f484e 100644 --- a/docs/sources/api/index.rst +++ b/docs/sources/api/index.rst @@ -2,8 +2,8 @@ :description: docker documentation :keywords: docker, ipa, documentation -API's -============= +APIs +==== This following : From 23452f1573e7887b638a4e69a4cf90d757921885 Mon Sep 17 00:00:00 2001 From: Daniel Gasienica Date: Sat, 1 Jun 2013 22:02:24 -0700 Subject: [PATCH 06/12] Use em dash in title --- docs/sources/concepts/introduction.rst | 4 ++-- docs/sources/index.rst | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/sources/concepts/introduction.rst b/docs/sources/concepts/introduction.rst index fcdd37a791..7251b51786 100644 --- a/docs/sources/concepts/introduction.rst +++ b/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. diff --git a/docs/sources/index.rst b/docs/sources/index.rst index 172f82083c..3e66fde1fb 100644 --- a/docs/sources/index.rst +++ b/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. From 2935ca7ee2879723c786b86ee87cc1be26dad7b8 Mon Sep 17 00:00:00 2001 From: Daniel Gasienica Date: Sat, 1 Jun 2013 22:03:12 -0700 Subject: [PATCH 07/12] Use title case for consistency --- docs/sources/contributing/devenvironment.rst | 4 ++-- docs/sources/examples/running_examples.rst | 2 +- docs/sources/use/basics.rst | 4 ++-- docs/sources/use/workingwithrepository.rst | 4 ++-- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/sources/contributing/devenvironment.rst b/docs/sources/contributing/devenvironment.rst index 0d202596c8..b5742c780a 100644 --- a/docs/sources/contributing/devenvironment.rst +++ b/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, diff --git a/docs/sources/examples/running_examples.rst b/docs/sources/examples/running_examples.rst index 3d2593c710..b6d6444aac 100644 --- a/docs/sources/examples/running_examples.rst +++ b/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: diff --git a/docs/sources/use/basics.rst b/docs/sources/use/basics.rst index 378028703c..444b74db51 100644 --- a/docs/sources/use/basics.rst +++ b/docs/sources/use/basics.rst @@ -3,8 +3,8 @@ :keywords: Examples, Usage, basic commands, docker, documentation, examples -The basics -============= +The Basics +========== Starting Docker --------------- diff --git a/docs/sources/use/workingwithrepository.rst b/docs/sources/use/workingwithrepository.rst index 9a2f96cf0d..db40245374 100644 --- a/docs/sources/use/workingwithrepository.rst +++ b/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 From 157547845acd8a0633df72e01d22bad9cbec578b Mon Sep 17 00:00:00 2001 From: Daniel Gasienica Date: Sat, 1 Jun 2013 22:03:28 -0700 Subject: [PATCH 08/12] Name examples consistently --- docs/sources/examples/couchdb_data_volumes.rst | 4 ++-- docs/sources/examples/python_web_app.rst | 4 ++-- docs/sources/examples/running_redis_service.rst | 4 ++-- docs/sources/examples/running_ssh_service.rst | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/sources/examples/couchdb_data_volumes.rst b/docs/sources/examples/couchdb_data_volumes.rst index 1b1d7ff79c..d6babe557f 100644 --- a/docs/sources/examples/couchdb_data_volumes.rst +++ b/docs/sources/examples/couchdb_data_volumes.rst @@ -4,8 +4,8 @@ .. _running_couchdb_service: -Create a CouchDB service -======================== +CouchDB Service +=============== .. include:: example_header.inc diff --git a/docs/sources/examples/python_web_app.rst b/docs/sources/examples/python_web_app.rst index 952ef62e33..8a4ca70750 100644 --- a/docs/sources/examples/python_web_app.rst +++ b/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 diff --git a/docs/sources/examples/running_redis_service.rst b/docs/sources/examples/running_redis_service.rst index 4b5d161e61..48d083aa8f 100644 --- a/docs/sources/examples/running_redis_service.rst +++ b/docs/sources/examples/running_redis_service.rst @@ -4,8 +4,8 @@ .. _running_redis_service: -Create a redis service -====================== +Redis Service +============= .. include:: example_header.inc diff --git a/docs/sources/examples/running_ssh_service.rst b/docs/sources/examples/running_ssh_service.rst index b262266dec..6183c3a55d 100644 --- a/docs/sources/examples/running_ssh_service.rst +++ b/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 From 4fb9a6eafb981ed66fe547fe29c11525f40d0640 Mon Sep 17 00:00:00 2001 From: Daniel Gasienica Date: Sat, 1 Jun 2013 22:03:41 -0700 Subject: [PATCH 09/12] Use code blocks --- docs/sources/use/workingwithrepository.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sources/use/workingwithrepository.rst b/docs/sources/use/workingwithrepository.rst index db40245374..6fccc01a98 100644 --- a/docs/sources/use/workingwithrepository.rst +++ b/docs/sources/use/workingwithrepository.rst @@ -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 /. This is what your published images will look like. +* User repositories always come in the form of ``/``. 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. From e9ffc1e49998d42f37b39cd23b56b73f7dc0e3da Mon Sep 17 00:00:00 2001 From: Daniel Gasienica Date: Sat, 1 Jun 2013 21:53:22 -0700 Subject: [PATCH 10/12] Add Node.js web app example using CentOS --- docs/sources/examples/index.rst | 3 +- docs/sources/examples/nodejs_web_app.rst | 225 +++++++++++++++++++++++ 2 files changed, 227 insertions(+), 1 deletion(-) create mode 100644 docs/sources/examples/nodejs_web_app.rst diff --git a/docs/sources/examples/index.rst b/docs/sources/examples/index.rst index 3a8e01fe03..d017f641b1 100644 --- a/docs/sources/examples/index.rst +++ b/docs/sources/examples/index.rst @@ -1,6 +1,6 @@ :title: Docker Examples :description: Examples on how to use Docker -:keywords: docker, hello world, python, couch, couchdb, redis, ssh, sshd, 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 diff --git a/docs/sources/examples/nodejs_web_app.rst b/docs/sources/examples/nodejs_web_app.rst new file mode 100644 index 0000000000..7c1df83776 --- /dev/null +++ b/docs/sources/examples/nodejs_web_app.rst @@ -0,0 +1,225 @@ +: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. + +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 ", + "dependencies": { + "express": "3.2.4" + } + } + +Then, create an ``index.js`` file that defines a web app using the +`Express.js `_ 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 `_ (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 + +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 + 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 /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 /centos-node-hello + +Print the output of your app: + +.. code-block:: bash + + # Get container ID + docker ps + + # Print app output + docker logs + + > # 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/ From 464765b940c8194c302b89891dc06b8fcc1b37ff Mon Sep 17 00:00:00 2001 From: Daniel Gasienica Date: Sat, 1 Jun 2013 22:16:26 -0700 Subject: [PATCH 11/12] Add link at the beginning --- docs/sources/examples/nodejs_web_app.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/sources/examples/nodejs_web_app.rst b/docs/sources/examples/nodejs_web_app.rst index 7c1df83776..56dab0c9aa 100644 --- a/docs/sources/examples/nodejs_web_app.rst +++ b/docs/sources/examples/nodejs_web_app.rst @@ -11,7 +11,8 @@ Node.js Web App 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. +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 ++++++++++++++++++ From 82dadc200593e39f0979159d46afccf64f1e7a83 Mon Sep 17 00:00:00 2001 From: Daniel Gasienica Date: Sun, 2 Jun 2013 20:10:22 -0700 Subject: [PATCH 12/12] Document installation of npm dependencies /ht @grigio --- docs/sources/examples/nodejs_web_app.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/sources/examples/nodejs_web_app.rst b/docs/sources/examples/nodejs_web_app.rst index 56dab0c9aa..376dc5c286 100644 --- a/docs/sources/examples/nodejs_web_app.rst +++ b/docs/sources/examples/nodejs_web_app.rst @@ -102,6 +102,13 @@ command: # 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: @@ -132,6 +139,9 @@ Your ``Dockerfile`` should now look like this: # Bundle app source ADD . /src + # Install app dependencies + RUN cd /src; npm install + EXPOSE 8080 CMD ["node", "/src/index.js"]