Update instructions for using BuildStream with Dockersam/use-via-docker

Changes:

  * use official image builds rather than suggesting users build and
    test their own
  * remove the `-u $UID` and /etc/passwd mount options; these didn't
    work on my system and I've not seen them needed
  * add SYS_ADMIN capability, /dev/fuse mount and remove seccomp.
    This reduces security but BuildStream does its own sandboxing
    in any case.

In future we will add a wrapper script which should simplify the
instuctions further.

1 files changed, 19 insertions, 73 deletions

diff --git a/doc/source/install.rst b/doc/source/install.rst
index b6bfb0699..0dc89c981 100644
--- a/doc/source/install.rst
+++ b/doc/source/install.rst
@@ -154,85 +154,31 @@ version of BuildStream.
 
 Using BuildStream inside Docker
 ===============================
-Some of the dependencies needed to use BuildStream are still not available in
-some Linux distributions.
 
-It is also possible that the users don't want to install these dependencies in
-their systems. For these cases, it's possible to use Docker.
+The BuildStream project provides
+`Docker images <https://hub.docker.com/r/buildstream/buildstream-fedora/>`
+containing BuildStream and its dependencies.
+This gives you an easy way to get started using BuildStream on any Unix-like
+platform where Docker is available, including Mac OS X.
 
-Here in this page we are going to explain how to use Docker for developing and
-running BuildStream.
-
-
-Building a Docker container to use BuildStream
-----------------------------------------------
-To create a Docker image ready to use with BuildStream you need to run the
-following command in the top level directory of BuildStream repository.
+To use BuildStream build tool you will need to spawn a container from that image
+and mount your workspace directory as a volume. You will want a second volume
+to store the cache, which we can create from empty like this:
 
 ::
 
-    docker build -t buildstream .
-
-Options explained:
-
--  ``-t buildstream``: Tag the created container as ``buildstream``
-
-The container created will have BuildStream installed. If you want to run a
-different version, you have to switch to the modified source tree and build the
-container image running the same command, or with a different tag.
-
-
-Running BuildStream tests in Docker
------------------------------------
-To run the tests inside a Docker container, we only need to mount the
-repository inside the running container and run the tests. To do this run the
-following command:
-
-::
-
-    docker run -it -u $UID:$EUID -v /etc/passwd:/etc/passwd \
-               -v `pwd`:/bst-src:rw \
-               --privileged -w /bst-src buildstream \
-	       python3 setup.py test
-
-Options explained:
-
--  ``-it``: Interactive shell and TTY support.
--  ``-u $UID:$EUID``: Use $UID as user-id and $EUID as group-id when
-   running the container.
--  ``-v /etc/passwd:/etc/passwd``: Mount passwd file in container to ensure
-   the user with uid $UID exists (Needed for bzr support).
--  ``-v $(pwd):/bst-src:rw``: Mount BuildStream source tree in
-   ``/bst-src`` with RW permissions.
--  ``--privileged``: To give extra privileges to the container (Needed
-   to run some of the sandbox tests).
--  ``-w /bst-src``: Switch to the ``/bst-src`` directory when running the
-   container.
-
-
-Using BuildStream in a Docker container
----------------------------------------
-To use BuildStream build tool you will need to mount inside the container your
-workspace, and a folder that BuildStream will use for temporary data. This way
-we make the temporary data persistent between runs.
+    docker volume create buildstream-cache
 
-Run the following command to run a bash session inside the container:
+You can now run the following command to fetch the latest official Docker image
+build, and spawn a container running an interactive shell. This assumes that the
+path to all the source code you need is available in ``~/src``.
 
 ::
 
-    docker run -it -u $UID:$EUID -v /etc/passwd:/etc/passwd \
-           -v /path/to/buildstream/workspace:/src:rw \
-	   -v /path/to/buildstream/tmp:/buildstream:rw \
-	   buildstream bash
-
-Options:
-
--  ``-it``: Interactive shell and TTY support.
--  ``-u $UID:$EUID``: Use $UID as user-id and $EUID as group-id when
-   running the container.
--  ``-v /etc/passwd:/etc/passwd``: Mount passwd file in container to ensure
-   the user with uid $UID exists (Needed for bzr support).
--  ``-v /path/to/buildstream/workspace:/src:rw``: Mount your workspace in
-   ``/src`` inside the container.
--  ``-v /path/to/buildstream/tmp:/buildstream:rw``: Mount a temporary folder
-   where BuildStream stores artifacts, sources, etc.
+    docker run -it \
+          --cap-add SYS_ADMIN \
+          --device /dev/fuse \
+          --security-opt seccomp=unconfined \
+          --volume ~/src:/src \
+          --volume buildstream-cache:/root/.cache \
+          buildstream/buildstream-fedora:latest /bin/bash