From fd6828a0f67d4f3a07c754e2e0df61acc209941c Mon Sep 17 00:00:00 2001 From: troymc Date: Wed, 15 Jun 2016 14:55:12 +0200 Subject: [PATCH] Move the Docker docs to a separate page --- docs/source/nodes/index.rst | 3 +- docs/source/nodes/run-with-docker.md | 120 +++++++++++++++++++++++++ docs/source/nodes/setup-run-node.md | 130 ++------------------------- 3 files changed, 130 insertions(+), 123 deletions(-) create mode 100644 docs/source/nodes/run-with-docker.md diff --git a/docs/source/nodes/index.rst b/docs/source/nodes/index.rst index 20fa4e33..f9a03180 100644 --- a/docs/source/nodes/index.rst +++ b/docs/source/nodes/index.rst @@ -20,11 +20,12 @@ Confusingly, we sometimes call a federation's cluster its "federation." You can :maxdepth: 1 node-requirements + federation-set-up setup-run-node + run-with-docker running-unit-tests configuration bigchaindb-cli python-server-api-examples - federation-set-up.md deploy-on-aws monitoring diff --git a/docs/source/nodes/run-with-docker.md b/docs/source/nodes/run-with-docker.md new file mode 100644 index 00000000..e39766d1 --- /dev/null +++ b/docs/source/nodes/run-with-docker.md @@ -0,0 +1,120 @@ +# Run BigchainDB with Docker + +**NOT for Production Use** + +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`. + +## Pull and Run the Image from Docker Hub + +Assuming you have Docker installed, you would proceed as follows. + +In a terminal shell, pull the latest version of the BigchainDB Docker image using: +```text +docker pull bigchaindb/bigchaindb +``` + +then do a one-time configuration step to create the config file; we will use +the `-y` option to accept all the default values. The configuration file will +be stored in a file on your host machine at `~/bigchaindb_docker/.bigchaindb`: + +```text +docker run --rm -v "$HOME/bigchaindb_docker:/data" -ti \ + bigchaindb/bigchaindb -y configure +Generating keypair +Configuration written to /data/.bigchaindb +Ready to go! +``` + +Let's analyze that command: + +* `docker run` tells Docker to run some image +* `--rm` remove the container once we are done +* `-v "$HOME/bigchaindb_docker:/data"` map the host directory + `$HOME/bigchaindb_docker` to the container directory `/data`; + 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/userguide/containers/dockervolumes/#mount-a-host-directory-as-a-data-volume) +* `-t` allocate a pseudo-TTY +* `-i` keep STDIN open even if not attached +* `bigchaindb/bigchaindb the image to use +* `-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 + + +After configuring the system, you can run BigchainDB with the following command: + +```text +docker run -v "$HOME/bigchaindb_docker:/data" -d \ + --name bigchaindb \ + -p "58080:8080" -p "59984:9984" \ + bigchaindb/bigchaindb start +``` + +The command is slightly different from the previous one, the differences are: + +* `-d` run the container in the background +* `--name bigchaindb` give a nice name to the container so it's easier to + refer to it later +* `-p "58080:8080"` map the host port `58080` to the container port `8080` + (the RethinkDB admin interface) +* `-p "59984:9984"` map the host port `59984` to the container port `9984` + (the BigchainDB API server) +* `start` start the BigchainDB service + +Another way to publish the ports exposed by the container is to use the `-P` (or +`--publish-all`) option. This will publish all exposed ports to random ports. You can +always run `docker ps` to check the random mapping. + +You can also access the RethinkDB dashboard at +[http://localhost:58080/](http://localhost:58080/) + +If that doesn't work, then replace `localhost` with the IP or hostname of the +machine running the Docker engine. If you are running docker-machine (e.g. on +Mac OS X) this will be the IP of the Docker machine (`docker-machine ip +machine_name`). + +### Load Testing with Docker + +Now that we have BigchainDB running in the Docker container named `bigchaindb`, we can +start another BigchainDB container to generate a load test for it. + +First, make sure the container named `bigchaindb` is still running. You can check that using: +```text +docker ps +``` + +You should see a container named `bigchaindb` in the list. + +You can load test the BigchainDB running in that container by running the `bigchaindb load` command in a second container: + +```text +docker run --rm -v "$HOME/bigchaindb_docker:/data" -ti \ + --link bigchaindb \ + bigchaindb/bigchaindb load +``` + +Note the `--link` option to link to the first container (named `bigchaindb`). + +Aside: The `bigchaindb load` command has several options (e.g. `-m`). You can read more about it in [the documentation about the BigchainDB command line interface](bigchaindb-cli.html). + +If you look at the RethinkDB dashboard (in your web browser), you should see the effects of the load test. You can also see some effects in the Docker logs using: +```text +docker logs -f bigchaindb +``` + +## Building Your Own Image + +Assuming you have Docker installed, you would proceed as follows. + +In a terminal shell: +```text +git clone git@github.com:bigchaindb/bigchaindb.git +``` + +Build the Docker image: +```text +docker build --tag local-bigchaindb . +``` + +Now you can use your own image to run BigchainDB containers. diff --git a/docs/source/nodes/setup-run-node.md b/docs/source/nodes/setup-run-node.md index 6e128e1e..3011bf02 100644 --- a/docs/source/nodes/setup-run-node.md +++ b/docs/source/nodes/setup-run-node.md @@ -59,7 +59,7 @@ If you're setting up a stand-alone node (i.e. not intending for it to join a clu ### Cluster Node -Create a RethinkDB configuration file (text file) named `instance.conf` in the `/etc/rethinkdb/instances.d/` directory with the following contents (explained below): +Create a RethinkDB configuration file (text file) named `instance1.conf` in the `/etc/rethinkdb/instances.d/` directory with the following contents (explained below): ```text directory=/data bind=all @@ -184,133 +184,19 @@ Once you've installed BigchainDB Server, you can run it. First make sure you hav rethinkdb ``` +TODO: What about `/etc/init.d/rethinkdb restart` + You can verify that RethinkDB is running by opening the RethinkDB web interface in your web browser. It should be at `http://rethinkdb-hostname:8080/`. If you're running RethinkDB on localhost, that would be [http://localhost:8080/](http://localhost:8080/). +TODO: Set shards using `bigchaindb set-shards numshards` + You can start BigchainDB Server using: ```text bigchaindb start ``` +OR: `screen -d -m bigchaindb -y start &` + + If it's the first time you've run `bigchaindb start`, then it creates the database (a RethinkDB database), the tables, the indexes, and the genesis block. It then starts BigchainDB. If you're run `bigchaindb start` or `bigchaindb init` before (and you haven't dropped the database), then `bigchaindb start` just starts BigchainDB. - -## Run BigchainDB with Docker - -**NOT for Production Use** - -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`. - -### Pull and Run the Image from Docker Hub - -Assuming you have Docker installed, you would proceed as follows. - -In a terminal shell, pull the latest version of the BigchainDB Docker image using: -```text -docker pull bigchaindb/bigchaindb -``` - -then do a one-time configuration step to create the config file; we will use -the `-y` option to accept all the default values. The configuration file will -be stored in a file on your host machine at `~/bigchaindb_docker/.bigchaindb`: - -```text -docker run --rm -v "$HOME/bigchaindb_docker:/data" -ti \ - bigchaindb/bigchaindb -y configure -Generating keypair -Configuration written to /data/.bigchaindb -Ready to go! -``` - -Let's analyze that command: - -* `docker run` tells Docker to run some image -* `--rm` remove the container once we are done -* `-v "$HOME/bigchaindb_docker:/data"` map the host directory - `$HOME/bigchaindb_docker` to the container directory `/data`; - 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/userguide/containers/dockervolumes/#mount-a-host-directory-as-a-data-volume) -* `-t` allocate a pseudo-TTY -* `-i` keep STDIN open even if not attached -* `bigchaindb/bigchaindb the image to use -* `-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 - - -After configuring the system, you can run BigchainDB with the following command: - -```text -docker run -v "$HOME/bigchaindb_docker:/data" -d \ - --name bigchaindb \ - -p "58080:8080" -p "59984:9984" \ - bigchaindb/bigchaindb start -``` - -The command is slightly different from the previous one, the differences are: - -* `-d` run the container in the background -* `--name bigchaindb` give a nice name to the container so it's easier to - refer to it later -* `-p "58080:8080"` map the host port `58080` to the container port `8080` - (the RethinkDB admin interface) -* `-p "59984:9984"` map the host port `59984` to the container port `9984` - (the BigchainDB API server) -* `start` start the BigchainDB service - -Another way to publish the ports exposed by the container is to use the `-P` (or -`--publish-all`) option. This will publish all exposed ports to random ports. You can -always run `docker ps` to check the random mapping. - -You can also access the RethinkDB dashboard at -[http://localhost:58080/](http://localhost:58080/) - -If that doesn't work, then replace `localhost` with the IP or hostname of the -machine running the Docker engine. If you are running docker-machine (e.g. on -Mac OS X) this will be the IP of the Docker machine (`docker-machine ip -machine_name`). - -#### Load Testing with Docker - -Now that we have BigchainDB running in the Docker container named `bigchaindb`, we can -start another BigchainDB container to generate a load test for it. - -First, make sure the container named `bigchaindb` is still running. You can check that using: -```text -docker ps -``` - -You should see a container named `bigchaindb` in the list. - -You can load test the BigchainDB running in that container by running the `bigchaindb load` command in a second container: - -```text -docker run --rm -v "$HOME/bigchaindb_docker:/data" -ti \ - --link bigchaindb \ - bigchaindb/bigchaindb load -``` - -Note the `--link` option to link to the first container (named `bigchaindb`). - -Aside: The `bigchaindb load` command has several options (e.g. `-m`). You can read more about it in [the documentation about the BigchainDB command line interface](bigchaindb-cli.html). - -If you look at the RethinkDB dashboard (in your web browser), you should see the effects of the load test. You can also see some effects in the Docker logs using: -```text -docker logs -f bigchaindb -``` - -### Building Your Own Image - -Assuming you have Docker installed, you would proceed as follows. - -In a terminal shell: -```text -git clone git@github.com:bigchaindb/bigchaindb.git -``` - -Build the Docker image: -```text -docker build --tag local-bigchaindb . -``` - -Now you can use your own image to run BigchainDB containers.