bigchaindb
/
bigchaindb
mirror of https://github.com/bigchaindb/bigchaindb.git
1
0
Fork 0
Code Releases Activity

Merge pull request #1825 from bigchaindb/docker-for-mac-quickstart 

Update quickstart guide for 'docker for mac' users
This commit is contained in:
Ahmed Muawia Khan 2017-11-16 16:55:31 +01:00 committed by GitHub
parent a4140e92a6 b4ca495967
commit 3752e13a38
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 16 additions and 232 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

101
docs/server/source/appendices/docker-on-mac.md
View File

@ -1,101 +0,0 @@
# 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
```

3
docs/server/source/appendices/index.rst
View File

@ -10,7 +10,6 @@ Appendices
install-os-level-deps
install-latest-pip
run-with-docker
docker-on-mac
json-serialization
cryptography
the-Bigchain-class
@ -28,4 +27,4 @@ Appendices
licenses
install-with-lxd
run-with-vagrant
run-with-ansible
run-with-ansible

26
docs/server/source/appendices/run-with-docker.md
View File

@ -6,9 +6,12 @@ For those who like using Docker and wish to experiment with BigchainDB in
non-production environments, we currently maintain a Docker image and a
`Dockerfile` that can be used to build an image for `bigchaindb`.
## Prerequisite(s)
- [Docker](https://docs.docker.com/engine/installation/)
## Pull and Run the Image from Docker Hub
Assuming you have Docker installed, you would proceed as follows.
With Docker installed, you can proceed as follows.
In a terminal shell, pull the latest version of the BigchainDB Docker image using:
```text
@ -26,6 +29,7 @@ docker run \
--rm \
--tty \
--volume $HOME/bigchaindb_docker:/data \
--env BIGCHAINDB_DATABASE_HOST=172.17.0.1 \
bigchaindb/bigchaindb \
-y configure \
[mongodb|rethinkdb]
@ -46,24 +50,18 @@ Let's analyze that command:
this allows us to have the data persisted on the host machine,
you can read more in the [official Docker
documentation](https://docs.docker.com/engine/tutorials/dockervolumes)
* `--env BIGCHAINDB_DATABASE_HOST=172.17.0.1`, `172.17.0.1` is the default `docker0` bridge
IP address, for fresh Docker installations. It is used for the communication between BigchainDB and database
containers.
* `bigchaindb/bigchaindb` the image to use. All the options after the container name are passed on to the entrypoint inside the container.
* `-y configure` execute the `configure` sub-command (of the `bigchaindb`
command) inside the container, with the `-y` option to automatically use all the default config values
* `mongodb` or `rethinkdb` specifies the database backend to use with bigchaindb
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
From v0.9 onwards, you can run either 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.
@ -73,8 +71,8 @@ You can also use docker host networking or bind to your primary (eth)
docker run \
--detach \
--name=rethinkdb \
--publish=172.17.0.1:28015:28015 \
--publish=172.17.0.1:58080:8080 \
--publish=28015:28015 \
--publish=58080:8080 \
--restart=always \
--volume $HOME/bigchaindb_docker:/data \
rethinkdb:2.3
@ -102,11 +100,11 @@ group.
docker run \
--detach \
--name=mongodb \
--publish=172.17.0.1:27017:27017 \
--publish=27017:27017 \
--restart=always \
--volume=$HOME/mongodb_docker/db:/data/db \
--volume=$HOME/mongodb_docker/configdb:/data/configdb \
mongo:3.4.1 --replSet=bigchain-rs
mongo:3.4.9 --replSet=bigchain-rs
```
### Run BigchainDB

4
docs/server/source/dev-and-test/index.rst
View File

@ -7,7 +7,7 @@ This section outlines some ways that you could set up a minimal BigchainDB node
:maxdepth: 1
Using a Local Dev Machine <setup-bdb-host>
Using a Local Dev Machine and Docker <setup-bdb-docker>
Using a Local Dev Machine and Docker <../appendices/run-with-docker>
Using Vagrant <../appendices/run-with-vagrant>
Using Ansible <../appendices/run-with-ansible>
running-all-tests
running-all-tests

112
docs/server/source/dev-and-test/setup-bdb-docker.md
View File

@ -1,112 +0,0 @@
# Set Up BigchainDB Node Using Docker
You need to have recent versions of [Docker](https://docs.docker.com/engine/installation/)
and (Docker) [Compose](https://docs.docker.com/compose/install/).
Build the images:
```bash
docker-compose build
```
## Docker with MongoDB
Start MongoDB:
```bash
docker-compose up -d mdb
```
MongoDB should now be up and running. You can check the port binding for the
MongoDB driver port using:
```bash
$ docker-compose port mdb 27017
```
Start a BigchainDB node:
```bash
docker-compose up -d bdb
```
You can monitor the logs:
```bash
docker-compose logs -f bdb
```
If you wish to run the tests:
```bash
docker-compose run --rm bdb py.test -v --database-backend=mongodb
```
## Docker with RethinkDB
**Note**: If you're upgrading BigchainDB and have previously already built the images, you may need
to rebuild them after the upgrade to install any new dependencies.
Start RethinkDB:
```bash
docker-compose -f docker-compose.rdb.yml up -d rdb
```
The RethinkDB web interface should be accessible at http://localhost:58080/.
Depending on which platform, and/or how you are running docker, you may need
to change `localhost` for the `ip` of the machine that is running docker. As a
dummy example, if the `ip` of that machine was `0.0.0.0`, you would access the
web interface at: http://0.0.0.0:58080/.
Start a BigchainDB node:
```bash
docker-compose -f docker-compose.rdb.yml up -d bdb-rdb
```
You can monitor the logs:
```bash
docker-compose -f docker-compose.rdb.yml logs -f bdb-rdb
```
If you wish to run the tests:
```bash
docker-compose -f docker-compose.rdb.yml run --rm bdb-rdb pytest -v -n auto
```
## Accessing the HTTP API
You can do quick check to make sure that the BigchainDB server API is operational:
```bash
curl $(docker-compose port bdb 9984)
```
The result should be a JSON object (inside braces like { })
containing the name of the software ("BigchainDB"),
the version of BigchainDB, the node's public key, and other information.
How does the above curl command work? Inside the Docker container, BigchainDB
exposes the HTTP API on port `9984`. First we get the public port where that
port is bound:
```bash
docker-compose port bdb 9984
```
The port binding will change whenever you stop/restart the `bdb` service. You
should get an output similar to:
```bash
0.0.0.0:32772
```
but with a port different from `32772`.
Knowing the public port we can now perform a simple `GET` operation against the
root:
```bash
curl 0.0.0.0:32772
```

2
docs/server/source/quickstart.md
View File

@ -1,6 +1,6 @@
# Quickstart
This page has instructions to set up a single stand-alone BigchainDB node for learning or experimenting. Instructions for other cases are [elsewhere](introduction.html). We will assume you're using Ubuntu 16.04 or similar. If you're not using Linux, then you might try [running BigchainDB with Docker](appendices/run-with-docker.html).
This page has instructions to set up a single stand-alone BigchainDB node for learning or experimenting. Instructions for other cases are [elsewhere](introduction.html). We will assume you're using Ubuntu 16.04 or similar. You can also try, [running BigchainDB with Docker](appendices/run-with-docker.html).
A. Install MongoDB as the database backend. (There are other options but you can ignore them for now.)