@@ -30,35 +30,58 @@ Each container can have zero or more data volumes.

 Getting Started

 ...............

-Using data volumes is as simple as adding a new flag: ``-v``. The

-parameter ``-v`` can be used more than once in order to create more

-volumes within the new container. The example below shows the

-instruction to create a container with two new volumes::

+Using data volumes is as simple as adding a ``-v`` parameter to the ``docker run`` 

+command. The ``-v`` parameter can be used more than once in order to 

+create more volumes within the new container. To create a new container with 

+two new volumes::

-  docker run -v /var/volume1 -v /var/volume2 shykes/couchdb

+  $ docker run -v /var/volume1 -v /var/volume2 busybox true

-For a Dockerfile, the VOLUME instruction will add one or more new

-volumes to any container created from the image::

+This command will create the new container with two new volumes that 

+exits instantly (``true`` is pretty much the smallest, simplest program 

+that you can run). Once created you can mount its volumes in any other 

+container using the ``-volumes-from`` option; irrespecive of whether the

+container is running or not. 

-  VOLUME ["/var/volume1", "/var/volume2"]

+Or, you can use the VOLUME instruction in a Dockerfile to add one or more new

+volumes to any container created from that image::

+  # BUILD-USING:        docker build -t data .

+  # RUN-USING:          docker run -name DATA data 

+  FROM          busybox

+  VOLUME        ["/var/volume1", "/var/volume2"]

+  CMD           ["/usr/bin/true"]

-Mount Volumes from an Existing Container:

+Creating and mounting a Data Volume Container

+---------------------------------------------

+

+If you have some persistent data that you want to share between containers, 

+or want to use from non-persistent containers, its best to create a named

+Data Volume Container, and then to mount the data from it.

+

+Create a named container with volumes to share (``/var/volume1`` and ``/var/volume2``)::

+

+  $ docker run -v /var/volume1 -v /var/volume2 -name DATA busybox true

+

+Then mount those data volumes into your application containers::

-The command below creates a new container which is running as daemon

-``-d`` and with one volume ``/var/lib/couchdb``::

+  $ docker run -t -i -rm -volumes-from DATA -name client1 ubuntu bash

-  COUCH1=$(sudo docker run -d -v /var/lib/couchdb shykes/couchdb:2013-05-03)

+You can use multiple ``-volumes-from`` parameters to bring together multiple 

+data volumes from multiple containers. 

-From the container id of that previous container ``$COUCH1`` it's

-possible to create new container sharing the same volume using the

-parameter ``-volumes-from container_id``::

+Interestingly, you can mount the volumes that came from the ``DATA`` container in 

+yet another container via the ``client1`` middleman container::

-  COUCH2=$(sudo docker run -d -volumes-from $COUCH1 shykes/couchdb:2013-05-03)

+  $ docker run -t -i -rm -volumes-from client1 ubuntu -name client2 bash

-Now, the second container has the all the information from the first volume.

+This allows you to abstract the actual data source from users of that data, 

+similar to :ref:`ambassador_pattern_linking <ambassador_pattern_linking>`.

+If you remove containers that mount volumes, including the initial DATA container, 

+or the middleman, the volumes will not be deleted until there are no containers still

+referencing those volumes. This allows you to upgrade, or effectivly migrate data volumes

+between containers.

 Mount a Host Directory as a Container Volume:

 ---------------------------------------------

@@ -68,13 +91,13 @@ Mount a Host Directory as a Container Volume:

   -v=[]: Create a bind mount with: [host-dir]:[container-dir]:[rw|ro].

   If "host-dir" is missing, then docker creates a new volume.

-This is not available for a Dockerfile due the portability and sharing

-purpose of it. The [host-dir] volumes is something 100% host dependent

-and will break on any other machine.

+This is not available from a Dockerfile as it makes the built image less portable

+or shareable. [host-dir] volumes are 100% host dependent and will break on any 

+other machine.

 For example::

-  sudo docker run -v /var/logs:/var/host_logs:ro shykes/couchdb:2013-05-03

+  sudo docker run -v /var/logs:/var/host_logs:ro ubuntu bash

 The command above mounts the host directory ``/var/logs`` into the

 container with read only permissions as ``/var/host_logs``.

@@ -87,3 +110,6 @@ Known Issues

 * :issue:`2702`: "lxc-start: Permission denied - failed to mount"

   could indicate a permissions problem with AppArmor. Please see the

   issue for a workaround.

+* :issue:`2528`:  the busybox container is used to make the resulting container as small and

+  simple as possible - whenever you need to interact with the data in the volume

+  you mount it into another container.