sijie commented on a change in pull request #342: Issue 338: add first draft Docker image including community suggestions URL: https://github.com/apache/bookkeeper/pull/342#discussion_r130797683
########## File path: docker/Readme.md ########## @@ -0,0 +1,169 @@ + +# What is Apache Bookkeeper? + +Apache ZooKeeper is a software project of the Apache Software Foundation, providing a replicated log service which can be used to build replicated state machines. A log contains a sequence of events which can be applied to a state machine. BookKeeper guarantees that each replica state machine will see all the same entries, in the same order. + +> [Apache Bookkeeper](http://bookkeeper.apache.org/) + + +# How to use this image + +Bookkeeper needs [Zookeeper](https://zookeeper.apache.org/) in order to preserve its state and publish its bookies (bookkepeer servers). The client only need to connect to a Zookkeeper server in the ensamble in order to obtain the list of Bookkeeper servers. + +## TL;DR + +If you just want to see things working, you can play with Makefile hosted in this project and check its targets for a fairly complex set up example: +``` +git clone https://github.com/apache/bookkeeper +cd bookkeeper/docker +make run-demo +``` +While, if you don't have access to a X environment, e.g. on default MacOS, It has to run the last command manually in 6 terminals respectively. +``` +make run-zk +make run-bk BOOKIE=1 +make run-bk BOOKIE=2 +make run-bk BOOKIE=3 +make run-dice +make run-dice +``` +This will do all the following steps and start up a working ensemble with two dice applications. + +## Step by step + +The simplest way to let Bookkeeper servers publish themselves with a name, which could be resolved consistently across container runs, is through creation of a [docker network](https://docs.docker.com/engine/reference/commandline/network_create/): +``` +docker network create "my-bookkeeper-network" +``` +Then we can start a Zookeeper (from [Zookeeper official image](https://hub.docker.com/_/zookeeper/)) server in standalone mode on that network: +``` +docker run -d \ + --network "my-bookkeeper-network" \ + --name "my-zookeeper" \ + --hostname "my-zookeeper" \ + zookeeper +``` +And initialize the filesystem that bookies will use to store informations: +``` +docker run -it --rm \ + --network "my-bookkeeper-network" \ + --env ZK_URL=my-zookeeper:2181 \ + bookkeeper \ + bookkeeper shell metaformat +``` +Now we can start our Bookkeeper ensamble (e.g. with three bookies): +``` +docker run -it\ + --network "my-bookkeeper-network" \ + --env ZK_URL=my-zookeeper:2181 \ + --name "bookie1" \ + --hostname "bookie1" \ + bookkeeper +``` +And so on for "bookie2" and "bookie3". We have now our fully functional ensemble, ready to accept clients. + +In order to play with our freshly created ensemble, you can use the simple application taken from [Bookkeeper Tutorial](http://bookkeeper.apache.org/docs/master/bookkeeperTutorial.html) and packaged in a [docker image](https://github.com/caiok/bookkeeper-tutorial) for convenience. +This application check if it can be leader, if yes start to roll a dice and book this rolls on bookkeeper, otherwise it will start to follow the leader rolls. If leader stops, follower will try to become leader and so on. + +Start a dice application (you can run it several times to view the behavior in a concurrent environment): +``` +docker run -it --rm \ + --network "my-bookkeeper-network" \ + --env ZOOKEEPER_SERVERS=my-zookkeeper:2181 \ + caiok/bookkeeper-tutorial +``` + +## Configuration Review comment: Can we standardize the environment variables with `BK_${setting_name}`? ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org With regards, Apache Git Services
