Merge pull request #9 from runabove/improve-readme

Improve README

README.md

@@ -1,93 +1,125 @@
-## QaaS client examples
+# OVH Paas Queue client examples
 
 [![Build Status](https://travis-ci.org/runabove/queue-examples.svg?branch=master)](https://travis-ci.org/runabove/queue-examples)
 
-* [Go](golang)
+* [Golang](golang)
 * [NodeJs](nodejs)
 * [Python](python)
 * [Scala](scala_kafka_0.8.2)
 
-# Basic concepts
+## Basic concepts
 
-Every client uses two constants :
+Each client example can be run in 2 modes: `produce` or `consume`.
 
-- Key   : The key used for the authentication. This key is linked to your application.
-- Topic : The topic to which data will be pushed. This topic should be prefixed
-    by your application id
+The two options `--key` and `--topic` are always mandatory:
 
-Every example uses the key as a client id to authenticate and pushed on a topic prefixed by the application id.
+- `--key` to configure the key to be authenticated to the OVH Paas Queue.
+- `--topic` to declare the authorized topic to produce to.
 
-# Golang
+Depending the client example needs the Kafka or the Zookeeper seed URL is used:
 
-## Requirements
+- `--kafka` for the Kafka broker seed URL
+- `--zk` for the Zookeeper broker seed URL
+
+In the `consume` mode:
+
+- `--group` is used to configure the consumer group id
+
+***Important to notice***:
+- ***The key is used as the Kafka client.id or the Zookeeper root path.***
+- ***The topic must be prefixed with the human application id corresponding to the key.***
+
+## Golang
+
+### Requirements
 
 * Go >= 1.5
 
-## Setup
+### Setup
 
 Build Go binary:
 
     make build-go
 
-## Consume data
+### Consume data
 
-    golang/bin/qaas-client-darwin-amd64 consume --kafka $HOST:9092 --key $KEY --topic $PREFIX.$TOPIC --group ${PREFIX}.golang-${GROUP}
+    golang/bin/qaas-client-darwin-amd64 consume \
+        --kafka $HOST:9092 --key $KEY --topic $PREFIX.$TOPIC --group ${PREFIX}.golang-${GROUP}
 
-## Produce data
+### Produce data
 
-    golang/bin/qaas-client-darwin-amd64 produce --kafka $HOST:9092 --key $KEY --topic $PREFIX.$TOPIC
+    golang/bin/qaas-client-darwin-amd64 produce \
+        --kafka $HOST:9092 --key $KEY --topic $PREFIX.$TOPIC
 
 # Node.js
 
-## Requirements
+### Requirements
 
 * Node.js
 * NPM
 
-## Setup
+### Setup
+
+Install the nodejs dependencies:
 
-Install Node dependencies:
+    make node-install-deps
+    cd nodejs
 
-  make build-node
+### Produce data
 
-## Produce data
+    node client.js produce \
+        --zk $HOST:2181 --key $KEY --topic $PREFIX.$TOPIC
 
-    node client.js produce --zk $HOST:2181 --key $KEY --topic $PREFIX.$TOPIC
+### Consume data
 
-## Consume data
+    node client.js consume \
+        --zk $HOST:2181 --key $KEY --topic $PREFIX.$TOPIC --group ${PREFIX}.nodejs-${GROUP}
 
-    node client.js consume --zk $HOST:2181 --key $KEY --topic $PREFIX.$TOPIC --group ${PREFIX}.nodejs-${GROUP}
+## Python
 
-# Python
+### Requirements
 
-## Requirements
+* Python >= 2.7
 
-* Python version 2.7
+### Setup
 
-## Setup
+Install the python dependencies:
 
-    make build-python
+    make python-install-deps
+    cd python
 
-## Produce
+### Produce
 
-~~~
- python client.py produce --kafka $HOST:9092 --key $KEY --topic $PREFIX.$TOPIC
-~~~
+    python client.py produce \
+        --kafka $HOST:9092 --key $KEY --topic $PREFIX.$TOPIC
 
-## Consume
+### Consume
 
-~~~
- python client.py consume --kafka $HOST:9092 --key $KEY --topic $PREFIX.$TOPIC --group ${PREFIX}.python-${GROUP}
- ~~~
+    python client.py consume \
+        --kafka $HOST:9092 --key $KEY --topic $PREFIX.$TOPIC --group ${PREFIX}.python-${GROUP}
 
-# Scala
+## Scala
 
 This example uses akka-reactive-streams and kafka 0.8.2.1.
 
-## Consume data
+### Setup
+
+* Scala
+* SBT
+
+### Consume data
+
+    sbt "run produce \
+        --kafka $HOST:9092 --zk $HOST:2181 --key $KEY --topic $PREFIX.$TOPIC"
+
+### Produce data
+
+    sbt "run consume \
+        --kafka $HOST:9092 --zk $HOST:2181 --key $KEY --topic $PREFIX.$TOPIC --group ${PREFIX}.scala-${GROUP}"
+
 
-    sbt "run produce--kafka $HOST:9092 --zk $HOST:2181 --key $KEY --topic $PREFIX.$TOPIC"
+## Docker
 
-## Produce data
+Each example can be build using Docker.
 
-    sbt "run consume --kafka $HOST:9092 --zk $HOST:2181 --key $KEY --topic $PREFIX.$TOPIC --group ${PREFIX}.python-${GROUP}"
+    make build-docker

golang/Makefile

@@ -1,13 +1,10 @@
 
-build-go:
-	go build -o qaas-client
-
 build-go-in-docker:
 	docker run --rm \
 		-e GOPATH=/go \
 		-e GOBIN=/go/bin/ \
 		-e CGO_ENABLED=0 \
 		-v $$(pwd):/go/src/github.com/runabove/queue-examples/golang \
 		-w /go/src/github.com/runabove/queue-examples/golang \
-		golang:1.6.2 \
-		sh -c "make build-go"
+			golang:1.6.2 \
+				go build -o qaas-client

python/Dockerfile

@@ -1,12 +1,9 @@
 FROM alpine:3.3
 
 RUN apk --no-cache add python py-pip
-#&& \
-    #pip install virtualenv
 
 WORKDIR /qaas-client
-#COPY requirements.txt /qaas-client/requirements.txt
-#RUN virtualenv /env && /env/bin/pip install -r /qaas-client/requirements.txt
+
 RUN pip install kafka-python==1.2.1
 
 COPY . /qaas-client