From 9c1e9a5157b3ef7627f4b735c2b8b6d97f26dd53 Mon Sep 17 00:00:00 2001 From: Andy Rothfusz Date: Fri, 6 Dec 2013 15:26:57 -0800 Subject: [PATCH] Fix #1229. Update titles, fix some wrapping. Make the Ambassador container explicit. Apply Sven's suggestions. --- .../use/ambassador_pattern_linking.rst | 6 +- docs/sources/use/baseimages.rst | 4 +- docs/sources/use/basics.rst | 6 +- docs/sources/use/builder.rst | 8 +- docs/sources/use/host_integration.rst | 6 +- docs/sources/use/index.rst | 2 +- docs/sources/use/networking.rst | 68 +++++++++------- docs/sources/use/port_redirection.rst | 6 +- docs/sources/use/working_with_links_names.rst | 81 ++++++++++--------- docs/sources/use/working_with_volumes.rst | 6 +- docs/sources/use/workingwithrepository.rst | 6 +- 11 files changed, 107 insertions(+), 92 deletions(-) diff --git a/docs/sources/use/ambassador_pattern_linking.rst b/docs/sources/use/ambassador_pattern_linking.rst index 095324cb16..d6d307783e 100644 --- a/docs/sources/use/ambassador_pattern_linking.rst +++ b/docs/sources/use/ambassador_pattern_linking.rst @@ -1,11 +1,11 @@ -:title: Ambassador pattern linking +:title: Link via an Ambassador Container :description: Using the Ambassador pattern to abstract (network) services :keywords: Examples, Usage, links, docker, documentation, examples, names, name, container naming .. _ambassador_pattern_linking: -Ambassador pattern linking -========================== +Link via an Ambassador Container +================================ Rather than hardcoding network links between a service consumer and provider, Docker encourages service portability. diff --git a/docs/sources/use/baseimages.rst b/docs/sources/use/baseimages.rst index f1f5d106e0..51a51e2f93 100644 --- a/docs/sources/use/baseimages.rst +++ b/docs/sources/use/baseimages.rst @@ -1,10 +1,10 @@ -:title: Base Image Creation +:title: Create a Base Image :description: How to create base images :keywords: Examples, Usage, base image, docker, documentation, examples .. _base_image_creation: -Base Image Creation +Create a Base Image =================== So you want to create your own :ref:`base_image_def`? Great! diff --git a/docs/sources/use/basics.rst b/docs/sources/use/basics.rst index 0881bde233..6b2c588817 100644 --- a/docs/sources/use/basics.rst +++ b/docs/sources/use/basics.rst @@ -1,10 +1,10 @@ -:title: Basic Commands +:title: Learn Basic Commands :description: Common usage and commands :keywords: Examples, Usage, basic commands, docker, documentation, examples -The Basics -========== +Learn Basic Commands +==================== Starting Docker --------------- diff --git a/docs/sources/use/builder.rst b/docs/sources/use/builder.rst index 2035c276dd..10140313a8 100644 --- a/docs/sources/use/builder.rst +++ b/docs/sources/use/builder.rst @@ -1,12 +1,12 @@ -:title: Dockerfiles for Images +:title: Build Images (Dockerfile Reference) :description: Dockerfiles use a simple DSL which allows you to automate the steps you would normally manually take to create an image. :keywords: builder, docker, Dockerfile, automation, image creation .. _dockerbuilder: -====================== -Dockerfiles for Images -====================== +=================================== +Build Images (Dockerfile Reference) +=================================== **Docker can act as a builder** and read instructions from a text ``Dockerfile`` to automate the steps you would otherwise take manually diff --git a/docs/sources/use/host_integration.rst b/docs/sources/use/host_integration.rst index a9f9c1e753..fb70195ffd 100644 --- a/docs/sources/use/host_integration.rst +++ b/docs/sources/use/host_integration.rst @@ -1,11 +1,11 @@ -:title: Host Integration +:title: Automatically Start Containers :description: How to generate scripts for upstart, systemd, etc. :keywords: systemd, upstart, supervisor, docker, documentation, host integration -Host Integration -================ +Automatically Start Containers +============================== You can use your Docker containers with process managers like ``upstart``, ``systemd`` and ``supervisor``. diff --git a/docs/sources/use/index.rst b/docs/sources/use/index.rst index ef95a517a7..7bcd1dd81e 100644 --- a/docs/sources/use/index.rst +++ b/docs/sources/use/index.rst @@ -17,9 +17,9 @@ Contents: workingwithrepository baseimages port_redirection - puppet networking host_integration working_with_volumes working_with_links_names ambassador_pattern_linking + puppet diff --git a/docs/sources/use/networking.rst b/docs/sources/use/networking.rst index c37035114e..0e81440e03 100644 --- a/docs/sources/use/networking.rst +++ b/docs/sources/use/networking.rst @@ -1,14 +1,14 @@ -:title: Docker networking +:title: Configure Networking :description: Docker networking :keywords: network, networking, bridge, docker, documentation -Networking -========== +Configure Networking +==================== -Docker uses Linux bridge capabilities to provide network connectivity -to containers. The ``docker0`` bridge interface is managed by Docker itself -for this purpose. Thus, when the Docker daemon starts it : +Docker uses Linux bridge capabilities to provide network connectivity +to containers. The ``docker0`` bridge interface is managed by Docker +itself for this purpose. Thus, when the Docker daemon starts it : - creates the ``docker0`` bridge if not present - searches for an IP address range which doesn't overlap with an existing route @@ -30,11 +30,12 @@ for this purpose. Thus, when the Docker daemon starts it : -At runtime, a :ref:`specific kind of virtual interface` is -given to each containers which is then bonded to the ``docker0`` bridge. -Each containers also receives a dedicated IP address from the same range -as ``docker0``. The ``docker0`` IP address is then used as the default -gateway for the containers. +At runtime, a :ref:`specific kind of virtual +interface` is given to each containers which is then +bonded to the ``docker0`` bridge. Each containers also receives a +dedicated IP address from the same range as ``docker0``. The +``docker0`` IP address is then used as the default gateway for the +containers. .. code-block:: bash @@ -47,18 +48,19 @@ gateway for the containers. docker0 8000.fef213db5a66 no vethQCDY1N -Above, ``docker0`` acts as a bridge for the ``vethQCDY1N`` interface which is dedicated -to the 52f811c5d3d6 container. +Above, ``docker0`` acts as a bridge for the ``vethQCDY1N`` interface +which is dedicated to the 52f811c5d3d6 container. How to use a specific IP address range --------------------------------------- -Docker will try hard to find an IP range which is not used by the host. -Even if it works for most cases, it's not bullet-proof and sometimes you need -to have more control over the IP addressing scheme. -For this purpose, Docker allows you to manage the ``docker0`` bridge or -your own one using the ``-b=`` parameter. +Docker will try hard to find an IP range which is not used by the +host. Even if it works for most cases, it's not bullet-proof and +sometimes you need to have more control over the IP addressing scheme. + +For this purpose, Docker allows you to manage the ``docker0`` bridge +or your own one using the ``-b=`` parameter. In this scenario: @@ -115,14 +117,15 @@ In this scenario: Container intercommunication ------------------------------- -Containers can communicate with each other according to the ``icc`` parameter -value of the Docker daemon. + +Containers can communicate with each other according to the ``icc`` +parameter value of the Docker daemon. - The default, ``-icc=true`` allows containers to communicate with each other. - ``-icc=false`` means containers are isolated from each other. -Under the hood, ``iptables`` is used by Docker to either accept or drop communication -between containers. +Under the hood, ``iptables`` is used by Docker to either accept or +drop communication between containers. .. _vethxxxx-device: @@ -131,17 +134,20 @@ What's about the vethXXXX device? ----------------------------------- Well. Things get complicated here. -The ``vethXXXX`` interface is the host side of a point-to-point link between the -host and the corresponding container, the other side of the link being -materialized by the container's ``eth0`` interface. This pair (host ``vethXXX`` and -container ``eth0``) are connected like a tube. Everything that comes in one side will -come out the other side. +The ``vethXXXX`` interface is the host side of a point-to-point link +between the host and the corresponding container, the other side of +the link being materialized by the container's ``eth0`` +interface. This pair (host ``vethXXX`` and container ``eth0``) are +connected like a tube. Everything that comes in one side will come out +the other side. -All the plumbing is delegated to Linux network capabilities (check the ip link -command) and the namespaces infrastructure. +All the plumbing is delegated to Linux network capabilities (check the +ip link command) and the namespaces infrastructure. I want more ------------ -Jérôme Petazzoni has create ``pipework`` to connect together containers in -arbitrarily complex scenarios : https://github.com/jpetazzo/pipework + +Jérôme Petazzoni has create ``pipework`` to connect together +containers in arbitrarily complex scenarios : +https://github.com/jpetazzo/pipework diff --git a/docs/sources/use/port_redirection.rst b/docs/sources/use/port_redirection.rst index adce1cba61..b35d27a3db 100644 --- a/docs/sources/use/port_redirection.rst +++ b/docs/sources/use/port_redirection.rst @@ -1,12 +1,12 @@ -:title: Port redirection +:title: Redirect Ports :description: usage about port redirection :keywords: Usage, basic port, docker, documentation, examples .. _port_redirection: -Port redirection -================ +Redirect Ports +============== Interacting with a service is commonly done through a connection to a port. When this service runs inside a container, one can connect to diff --git a/docs/sources/use/working_with_links_names.rst b/docs/sources/use/working_with_links_names.rst index 6283a865f8..8c654cbdbc 100644 --- a/docs/sources/use/working_with_links_names.rst +++ b/docs/sources/use/working_with_links_names.rst @@ -1,15 +1,16 @@ -:title: Working with Links and Names -:description: How to create and use links and names +:title: Link Containers +:description: How to create and use both links and names :keywords: Examples, Usage, links, linking, docker, documentation, examples, names, name, container naming .. _working_with_links_names: -Working with Links and Names -============================ +Link Containers +=============== -From version 0.6.5 you are now able to ``name`` a container and ``link`` it to another -container by referring to its name. This will create a parent -> child relationship -where the parent container can see selected information about its child. +From version 0.6.5 you are now able to ``name`` a container and +``link`` it to another container by referring to its name. This will +create a parent -> child relationship where the parent container can +see selected information about its child. .. _run_name: @@ -18,8 +19,9 @@ Container Naming .. versionadded:: v0.6.5 -You can now name your container by using the ``-name`` flag. If no name is provided, Docker -will automatically generate a name. You can see this name using the ``docker ps`` command. +You can now name your container by using the ``-name`` flag. If no +name is provided, Docker will automatically generate a name. You can +see this name using the ``docker ps`` command. .. code-block:: bash @@ -38,18 +40,21 @@ Links: service discovery for docker .. versionadded:: v0.6.5 -Links allow containers to discover and securely communicate with each other by using the -flag ``-link name:alias``. Inter-container communication can be disabled with the daemon -flag ``-icc=false``. With this flag set to ``false``, Container A cannot access Container B -unless explicitly allowed via a link. This is a huge win for securing your containers. -When two containers are linked together Docker creates a parent child relationship -between the containers. The parent container will be able to access information via -environment variables of the child such as name, exposed ports, IP and other selected -environment variables. +Links allow containers to discover and securely communicate with each +other by using the flag ``-link name:alias``. Inter-container +communication can be disabled with the daemon flag +``-icc=false``. With this flag set to ``false``, Container A cannot +access Container B unless explicitly allowed via a link. This is a +huge win for securing your containers. When two containers are linked +together Docker creates a parent child relationship between the +containers. The parent container will be able to access information +via environment variables of the child such as name, exposed ports, IP +and other selected environment variables. -When linking two containers Docker will use the exposed ports of the container to create -a secure tunnel for the parent to access. If a database container only exposes port 8080 -then the linked container will only be allowed to access port 8080 and nothing else if +When linking two containers Docker will use the exposed ports of the +container to create a secure tunnel for the parent to access. If a +database container only exposes port 8080 then the linked container +will only be allowed to access port 8080 and nothing else if inter-container communication is set to false. For example, there is an image called ``crosbymichael/redis`` that exposes the @@ -60,26 +65,28 @@ based on that image and run it as daemon. $ sudo docker run -d -name redis crosbymichael/redis -We can issue all the commands that you would expect using the name ``redis``; start, stop, -attach, using the name for our container. The name also allows us to link other containers -into this one. +We can issue all the commands that you would expect using the name +``redis``; start, stop, attach, using the name for our container. The +name also allows us to link other containers into this one. -Next, we can start a new web application that has a dependency on Redis and apply a link -to connect both containers. If you noticed when running our Redis server we did not use -the ``-p`` flag to publish the Redis port to the host system. Redis exposed port 6379 and -this is all we need to establish a link. +Next, we can start a new web application that has a dependency on +Redis and apply a link to connect both containers. If you noticed when +running our Redis server we did not use the ``-p`` flag to publish the +Redis port to the host system. Redis exposed port 6379 and this is all +we need to establish a link. .. code-block:: bash $ sudo docker run -t -i -link redis:db -name webapp ubuntu bash -When you specified ``-link redis:db`` you are telling Docker to link the container named ``redis`` -into this new container with the alias ``db``. Environment variables are prefixed with the alias -so that the parent container can access network and environment information from the containers -that are linked into it. +When you specified ``-link redis:db`` you are telling Docker to link +the container named ``redis`` into this new container with the alias +``db``. Environment variables are prefixed with the alias so that the +parent container can access network and environment information from +the containers that are linked into it. -If we inspect the environment variables of the second container, we would see all the information -about the child container. +If we inspect the environment variables of the second container, we +would see all the information about the child container. .. code-block:: bash @@ -101,10 +108,12 @@ about the child container. _=/usr/bin/env root@4c01db0b339c:/# -Accessing the network information along with the environment of the child container allows -us to easily connect to the Redis service on the specific IP and port in the environment. +Accessing the network information along with the environment of the +child container allows us to easily connect to the Redis service on +the specific IP and port in the environment. -Running ``docker ps`` shows the 2 containers, and the ``webapp/db`` alias name for the redis container. +Running ``docker ps`` shows the 2 containers, and the ``webapp/db`` +alias name for the redis container. .. code-block:: bash diff --git a/docs/sources/use/working_with_volumes.rst b/docs/sources/use/working_with_volumes.rst index 9156e574d0..b5ef991138 100644 --- a/docs/sources/use/working_with_volumes.rst +++ b/docs/sources/use/working_with_volumes.rst @@ -1,11 +1,11 @@ -:title: Working with Volumes +:title: Share Directories via Volumes :description: How to create and share volumes :keywords: Examples, Usage, volume, docker, documentation, examples .. _volume_def: -Data Volume -=========== +Share Directories via Volumes +============================= .. versionadded:: v0.3.0 Data volumes have been available since version 1 of the diff --git a/docs/sources/use/workingwithrepository.rst b/docs/sources/use/workingwithrepository.rst index 3797f6ab52..38062556cb 100644 --- a/docs/sources/use/workingwithrepository.rst +++ b/docs/sources/use/workingwithrepository.rst @@ -1,11 +1,11 @@ -:title: Working With Repositories +:title: Share Images via Repositories :description: Repositories allow users to share images. :keywords: repo, repositories, usage, pull image, push image, image, documentation .. _working_with_the_repository: -Working with Repositories -========================= +Share Images via Repositories +============================= A *repository* is a hosted collection of tagged :ref:`images ` that together create the file system for a container. The