Updated docker/README

- Legacy-Id: 10438

docker/README.rst

@@ -17,65 +17,82 @@ get started with datatracker development.
 Steps
 =====
 
-1. Set up Docker on your preferred platform.  `Official installers`_
+1. Set up Docker on your preferred platform.  Official installers
    exist for many Linux flavours, OS X, Windows and Cloud services.
 
    Docker containers require the services of an underlying Linux API,
    which means that on OS X and Windows, these have to be provided
    by a virtual machine which runs a minimal Linux image.  The virtual
-   machine used is VirtualBox_, and the official installer provides an
-   image named Docker Machine.
+   machine used is commonly VirtualBox, although at least one
+   unofficial VM image and controller (boot2docker_) also supports
+   Parallels, XenServer and VMWare.
 
-   Another option is boot2docker_, which is deprecated as of end 2015,
-   but has worked well for me, something I unfortunately cannot say for
-   the Docker Machine as of November 2015.  It seems to me as if boot2docker
-   has been deprecated before the Docker Machine was quite ready for
-   prime time.
+   The primary installers available is the unofficial boot2docker_ and
+   the official `Docker Engine`_.  I've tried both, and at this time,
+   November 2015, boot2docker has worked much better for me than
+   Docker Engine.  YMMV.
 
-2. Check out your datatracker branch in a suitable directory.  We'll
-   assume ``~/src/dt/`` here, and assume you are ``coder``::
+   Boot2docker can self-upgrade and provides up-to-date docker server
+   and clients.  Run update after you install::
+
+      ~ $ boot2docker upgrade
+
+2. Check out your datatracker branch as usual, in a suitable directory.
+   We'll assume ``~/src/dt/`` here, and assume you are ``'coder'``::
 
       ~/src/dt/ $ svn co https://svn.tools.ietf.org/svn/tools/ietfdb/personal/coder/6.8.2.dev0
 
-3. In the checked out working copy, you'll find a ``data/`` directory
+3. In the checked-out working copy, you'll find a ``data/`` directory
    at the top level.  Fetch down a pre-built copy of the datatracker
-   database, place it in this directory and unpack it::
+   database, place it in this directory, unpack it, and fix permissions::
 
       ~/src/dt/6.8.2.dev0/data/ $ wget https://www.ietf.org/lib/dt/sprint/ietf_utf8.bin.tar.bz2 .
       ~/src/dt/6.8.2.dev0/data/ $ tar xjf ietf_utf8.bin.tar.bz2
+      ~/src/dt/6.8.2.dev0/data/ $ chmod -R go+rwX mysql
 
-4. In the checked out working copy, you'll also find a ``docker/``
+4. In the checked-out working copy, you'll also find a ``docker/``
    directory at the top level.  It contains a Dockerfile which can
-   be used to build a docker image, but we will be using a prebuilt
-   image::
+   be used to build a docker image, but that doesn't concern us at
+   the moment.  We will be using a wrapper script, ``'run'``, to
+   run a pre-built docker image fetched from the docker hub::
 
       ~/src/dt/6.8.2.dev0/docker/ $ ./run
 
    This will pull down the latest docker datatracker image, start it
    up with appropriate settings, map the internal ``/var/lib/mysql/``
-   directory to the ``data/mysql/`` directory we placed the database
-   in, set up a python virtualenv for you, install some dependencies,
-   and drop you in a bash shell.
+   directory to the external ``data/mysql/`` directory where we placed
+   the database, set up a python virtualenv for you, install some
+   dependencies, and drop you in a bash shell where you can run the
+   datatracker.
 
-5. You are now free to run the tests **in the virtual environment**::
+5. Make sure that all requirements are installed::
 
-      (datatracker) $ ietf/manage.py test --settings=settings_sqlitetest
+      (virtual) $ cd ~/src/dt/6.8.2.dev0
+      (virtual) $ pip install -r requirements.txt
+
+6. You are now ready to run the tests::
+
+      (virtual) $ ietf/manage.py test --settings=settings_sqlitetest
 
    and then start the dev server::
 
-      (datatracker) $ ietf/manage.py runserver 0.0.0.0:8000
+      (virtual) $ ietf/manage.py runserver 0.0.0.0:8000
 
-   Note the IP address ``0.0.0.0`` used to make the dev server bind to all
-   addresses.  The internal port 8000 has been mapped to port 8000 externally,
-   too, by the ``run`` command.  In order to find the IP address of the
-   VirtualBox, run ``$ boot2docker ip`` or equivalent::
+   Note the IP address ``0.0.0.0`` used to make the dev server bind
+   to all addresses.  The internal port 8000 has been mapped to port
+   8000 externally, too.  In order to find the IP address of the
+   VirtualBox, run ``'$ boot2docker ip'`` or equivalent *outside* the
+   virtual environment::
 
       ~/src/dt/6.8.2.dev0/ $ boot2docker ip
       192.168.59.103
-      
-      ~/src/dt/6.8.2.dev0/ $ open -a Safari http://192.168.59.103:8000/
+
+      ~/src/dt/6.8.2.dev0/ $ open http://192.168.59.103:8000/
+
 
 ..  _Docker: https://www.docker.com/
-..  _`Official installers`: https://docs.docker.com/engine/installation/
+..  _`Docker Engine`: https://docs.docker.com/engine/installation/
 ..  _boot2docker: http://boot2docker.io/
 ..  _VirtualBox: https://www.virtualbox.org/
+
+