Documentation for running BigchainDB in docker containers on mac (#1265)

* Documentation for running bigchaindb docker image on mac

docs/server/source/appendices/docker-on-mac.md

@@ -0,0 +1,101 @@
+# Run BigchainDB with Docker On Mac
+
+**NOT for Production Use**
+
+Those developing on Mac can follow this document to run BigchainDB in docker
+containers for a quick dev setup.
+Running BigchainDB on Mac (Docker or otherwise) is not officially supported.
+
+Support is very much limited as there are certain things that work differently
+in Docker for Mac than Docker for other platforms.
+Also, we do not use mac for our development and testing. :)
+
+This page may not be up to date with various settings and docker updates at
+all the times.
+
+These steps work as of this writing (2017.Mar.09) and might break in the
+future with updates to Docker for mac.
+Community contribution to make BigchainDB run on Docker for Mac will always be
+welcome.
+
+
+## Prerequisite
+
+Install Docker for Mac.
+
+## (Optional) For a clean start
+
+1.  Stop all BigchainDB and RethinkDB/MongoDB containers.
+2.  Delete all BigchainDB docker images.
+3.  Delete the ~/bigchaindb_docker folder.
+
+
+## Pull the images
+
+Pull the bigchaindb and other required docker images from docker hub.
+
+```text
+docker pull bigchaindb/bigchaindb:master
+docker pull [rethinkdb:2.3|mongo:3.4.1]
+```
+
+## Create the BigchainDB configuration file on Mac
+```text
+docker run \
+  --rm \
+  --volume $HOME/bigchaindb_docker:/data \
+  bigchaindb/bigchaindb:master \
+  -y configure \
+  [mongodb|rethinkdb]
+```
+
+To ensure that BigchainDB connects to the backend database bound to the virtual
+interface `172.17.0.1`, you must edit the BigchainDB configuration file
+(`~/bigchaindb_docker/.bigchaindb`) and change database.host from `localhost`
+to `172.17.0.1`.
+
+
+## Run the backend database on Mac
+
+From v0.9 onwards, you can run RethinkDB or MongoDB.
+
+We use the virtual interface created by the Docker daemon to allow
+communication between the BigchainDB and database containers.
+It has an IP address of 172.17.0.1 by default.
+
+You can also use docker host networking or bind to your primary (eth)
+interface, if needed.
+
+### For RethinkDB backend
+```text
+docker run \
+  --name=rethinkdb \
+  --publish=28015:28015 \
+  --publish=8080:8080 \
+  --restart=always \
+  --volume $HOME/bigchaindb_docker:/data \
+  rethinkdb:2.3
+```
+
+### For MongoDB backend
+```text
+docker run \
+  --name=mongodb \
+  --publish=27017:27017 \
+  --restart=always \
+  --volume=$HOME/bigchaindb_docker/db:/data/db \
+  --volume=$HOME/bigchaindb_docker/configdb:/data/configdb \
+  mongo:3.4.1 --replSet=bigchain-rs
+```
+
+### Run BigchainDB on Mac
+```text
+docker run \
+  --name=bigchaindb \
+  --publish=9984:9984 \
+  --restart=always \
+  --volume=$HOME/bigchaindb_docker:/data \
+  bigchaindb/bigchaindb \
+  start
+```
+

docs/server/source/appendices/index.rst

@@ -10,6 +10,7 @@ Appendices
    install-os-level-deps
    install-latest-pip
    run-with-docker
+   docker-on-mac
    json-serialization
    cryptography
    the-Bigchain-class

docs/server/source/appendices/run-with-docker.md

@@ -25,7 +25,7 @@ docker run \
   --interactive \
   --rm \
   --tty \
-  --volume "$HOME/bigchaindb_docker:/data" \
+  --volume $HOME/bigchaindb_docker:/data \
   bigchaindb/bigchaindb \
   -y configure \
   [mongodb|rethinkdb]
@@ -76,7 +76,7 @@ docker run \
   --publish=172.17.0.1:28015:28015 \
   --publish=172.17.0.1:58080:8080 \
   --restart=always \
-  --volume "$HOME/bigchaindb_docker:/data" \
+  --volume $HOME/bigchaindb_docker:/data \
   rethinkdb:2.3
 ```
 
@@ -95,7 +95,7 @@ be owned by this user in the host.
 If there is no owner with UID 999, you can create the corresponding user and
 group.
 
-`groupadd -r --gid 999 mongodb && useradd -r --uid 999 -g mongodb mongodb`
+`useradd -r --uid 999 mongodb` OR `groupadd -r --gid 999 mongodb && useradd -r --uid 999 -g mongodb mongodb` should work.
 
 
 ```text
@@ -156,3 +156,4 @@ docker build --tag local-bigchaindb .
 ```
 
 Now you can use your own image to run BigchainDB containers.
+