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..74ab2bd0cd 100644 --- a/docs/README.md +++ b/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 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. \ No newline at end of file + Start without $, so it's easy to copy and paste. 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 : 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/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/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/index.rst b/docs/sources/examples/index.rst index 7eb2ecbe94..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, 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..376dc5c286 --- /dev/null +++ b/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 ", + "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 + +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 /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/ 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_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/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 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. 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..6fccc01a98 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 @@ -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.