diff --git a/docs/source/bigchaindb-cli.md b/docs/source/bigchaindb-cli.md index d154e118..229d5b4c 100644 --- a/docs/source/bigchaindb-cli.md +++ b/docs/source/bigchaindb-cli.md @@ -37,9 +37,9 @@ This command drops (erases) the RethinkDB database. You will be prompted to make This command starts BigchainDB. It always begins by trying a `bigchaindb init` first. See the note in the documentation for `bigchaindb init`. -## bigchaindb load +### bigchaindb load -The command is used to run benchmarking tests. You can learn more about it using: +This command is used to run benchmarking tests. You can learn more about it using: ```text $ bigchaindb load -h ``` diff --git a/docs/source/installing-server.md b/docs/source/installing-server.md index 60fd977d..1b830811 100644 --- a/docs/source/installing-server.md +++ b/docs/source/installing-server.md @@ -113,104 +113,108 @@ If it's the first time you've run `bigchaindb start`, then it creates the databa 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`. +`Dockerfile` that can be used to build an image for `bigchaindb`. -### Pull and run the image from Docker Hub +### Pull and Run the Image from Docker Hub -Assuming you have `docker` installed, you would proceed as follows. +Assuming you have Docker installed, you would proceed as follows. -In a terminal shell, pull the latest version of the BigchainDB Docker image +In a terminal shell, pull the latest version of the BigchainDB Docker image using: ```text docker pull bigchaindb/bigchaindb:latest ``` 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 on your host machine under ` ~/bigchaindb_docker/.bigchaindb`: +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:latest configure + bigchaindb/bigchaindb:latest -y configure Generating keypair Configuration written to /data/.bigchaindb Ready to go! ``` -Let's analyze the command: - - `docker run` tell 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 allow 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:latest` the image to use - - `configure` the sub-command to execute +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:latest` 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: +After configuring the system, you can run BigchainDB with the following command: ```text $ docker run -v "$HOME/bigchaindb_docker:/data" -d \ - --name bigchaindb + --name bigchaindb \ -p "58080:8080" -p "59984:9984" \ bigchaindb/bigchaindb:latest start ``` The command is slightly different from the previous one, the differences are: - - `--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 containeris to use the `-P` (or -`--publish-all`). This will publish all exposed ports to random ports. You can +* `-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: +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 +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 test with Docker +#### Load Testing with Docker -After BigchainDB is running in the docker container named `bigchaindb`, we can -start another container and run the load test against the first one. +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 `bigchaindb` is running, you can check this by running: +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` running. +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: -Now, run a new container and link it to `bigchaindb` to run the load test. ```text $ docker run --rm -v "$HOME/bigchaindb_docker:/data" -ti \ --link bigchaindb \ - bigchaindb/bigchaindb:test load + bigchaindb/bigchaindb:latest load ``` -Note that load test transactions accepts also a `-m` option to enable -multiprocessing and make use of all the cores in the host machine. +Note the `--link` option to link to the first container (named `bigchaindb`). -You can see BigchainDB processing your transactions running: +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 +### Building Your Own Image -Assuming you have `docker` installed, you would proceed as follows. +Assuming you have Docker installed, you would proceed as follows. In a terminal shell: ```text @@ -223,4 +227,3 @@ $ docker build --tag local-bigchaindb . ``` Now you can use your own image to run BigchainDB containers. -