openwhisk-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From csantan...@apache.org
Subject [incubator-openwhisk-package-kafka] branch master updated: create development guide (#187)
Date Mon, 14 Aug 2017 15:55:39 GMT
This is an automated email from the ASF dual-hosted git repository.

csantanapr pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-openwhisk-package-kafka.git


The following commit(s) were added to refs/heads/master by this push:
     new 7c1e0c0  create development guide (#187)
7c1e0c0 is described below

commit 7c1e0c09403dbe6e47acc198a7a67e3b79bf7516
Author: Justin Berstler <bjustin@us.ibm.com>
AuthorDate: Mon Aug 14 11:55:37 2017 -0400

    create development guide (#187)
---
 README.md   |  4 ++--
 devGuide.md | 62 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 64 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index a439e71..ec475af 100644
--- a/README.md
+++ b/README.md
@@ -280,8 +280,8 @@ The action caller (you, or your code) must first Base64 encode the data,
for exa
 ### Integrating OpenWhisk with IBM Message Hub, Node Red, IBM Watson IoT, IBM Object Storage,
and IBM Data Science Experience
 Example that integrates OpenWhisk with IBM Message Hub, Node Red, IBM Watson IoT, IBM Object
Storage, IBM Data Science Experience (Spark) service can be [found here](https://medium.com/openwhisk/transit-flexible-pipeline-for-iot-data-with-bluemix-and-openwhisk-4824cf20f1e0).
 
-## Testing
-An OpenWhisk deployment is required in order for the automated test suite to be executed.
To run tests locally, run ```$ ./gradlew tests:test -Dhost=<container_address> -Dport=<docker_port>```
from the project's root directory. Where ```<docker_address>``` is the IP address of
the service's docker container, and ```<docker_port>``` is the port the docker container
is listening on. In addition, ```OPENWHISK_HOME``` must be set to the root of the local OpenWhisk
directory. Ex: ```export OP [...]
+## Development and Testing
+If you wish to deploy the feed service yourself, please refer to the [Development Guide](devGuide.md).
 
 ## References
 - [OpenWhisk](https://www.ibm.com/cloud-computing/bluemix/openwhisk)
diff --git a/devGuide.md b/devGuide.md
new file mode 100644
index 0000000..81080dc
--- /dev/null
+++ b/devGuide.md
@@ -0,0 +1,62 @@
+# Development and Testing
+## Build
+Building the Kafka feed provider is a simple matter of running a `docker build` command from
the root of the project. I suggest tagging the image with a memorable name, like "kafkafeedprovider":
+
+``` sh
+docker build -t kafkafeedprovider .
+```
+
+## Run
+Now we need to start the provider service. This is also a simple matter of running a `docker
run` command, but the details are a little tricky. The service relies on a number of environment
variables in order to operate properly. They are outlined below:
+
+### Mandatory Environment Variables
+|Name|Type|Description|
+|---|---|---|
+|DB_URL|URL|The base URL for persistent storage (either CouchDB or Cloudant)|
+|DB_USER|String|Username for your DB credentials|
+|DB_PASS|String|Password for your DB credentials|
+
+### Optional Environment Variables
+|Name|Type|Description|
+|---|---|---|
+|INSTANCE|String|A unique identifier for this service. This is useful to differentiate log
messages if you run multiple instances of the service|
+|LOCAL_DEV|Boolean|If you are using a locally-deployed OpenWhisk core system, it likely has
a self-signed certificate. Set `LOCAL_DEV` to `true` to allow firing triggers without checking
the certificate validity. *Do not use this for production systems!*|
+|PAYLOAD_LIMIT|Integer (default=900000)|The maxmimum payload size, in bytes, allowed during
message batching. This value should be less than your OpenWhisk deployment's payload limit.|
+
+With that in mind, starting the feed service might look something like:
+
+```sh
+docker run -e DB_URL=https://myDbHost -e DB_USER=MyDbUser -e DB_PASS=MySuperSecret -p 80:5000
kafkafeedprovider
+```
+
+This example will start the provider service with the specified DB details. The container
provides a number of RESTful endpoints which can be accessed on port 5000 _inside_ the container.
To expose this port to the rest of the world `-p 80:5000` tells Docker to map port 80 of the
host machine into port 5000 inside this new container.
+
+After issuing the `docker run` command, you can confirm the service started correctly by
inspecting the container with a `docker logs` command.
+
+# Install Actions
+The provided actions also need to be installed to your OpenWhisk deployment. We have automated
this with two different shell scripts, one for Message Hub related actions, and one for generic
Kafka related actions. These scripts are `installCatalog.sh` and `installKafka.sh`, respectively.
+
+Each script requires a number of arguments which are outlined below:
+
+|Name|Description|
+|---|---|
+|authKey|The OpenWhisk auth key to use when installing the actions. Typically this would
be the auth key for `whisk.system`|
+|edgehost|The IP address or hostname of the OpenWhisk core system.|
+|dburl|The full URL (including credentials) of the CouchDB or Cloudant account used by the
feed service.|
+|dbprefix|A prefix to be prepended to the default DB name (ow_kafka_triggers) that will be
created by the provider service.|
+|apihost|The hostname or IP address of the core OpenWhisk system that will be used as the
hostname for all trigger URLs. In most cases, this will be the same as `edgehost`.|
+
+An example run might look something like:
+
+```sh
+./installKafka.sh MyOpenWhiskAuthKey 10.0.1.5 https://cloudant_user:cloudant_pw@cloudant.com
staging_db_prefix 10.0.1.5
+```
+
+# Testing
+To run the automated test suite, you can issue a Gradle command. There are some tests which
talk directly to the provider service over REST, and so these tests must know the IP address
and port of the running service. This is done by providing the `-Dhealth_url`, `-Dhost` and
`-Dport` arguments to Gradle:
+
+```sh
+./gradlew :tests:test -Dhealth_url=http://127.0.0.1/health -Dhost=127.0.0.1 -Dport=80
+```
+
+The value of the `host` must be the IP/hostname of the Docker host running the service provider
container, and the `port` must be the exposed port number. Additionally, the `OPENWHISK_HOME`
environment variable must be set to the root of the local OpenWhisk directory. Ex: `export
OPENWHISK_HOME=<openwhisk_directory>`.

-- 
To stop receiving notification emails like this one, please contact
['"commits@openwhisk.apache.org" <commits@openwhisk.apache.org>'].

Mime
View raw message