sbt-conductr-sandbox aims to support the running of a Docker-based ConductR cluster in the context of a build. The cluster can then be used to assist you in order to verify that endpoint declarations and other aspects of a bundle configuration are correct. The general idea is that this plugin will also support you when building your project on CI so that you may automatically verify that it runs on ConductR.

The single node version of the ConductR Developer Sandbox is available gratis with registration at Typesafe.com. Please visit the ConductR Developer page on Typesafe.com for the current image version and licensing information. Use of the ConductR in multi-node mode or for production purposes requires the purchase of Typesafe ConductR.

If you have not done so already, then please install Docker.

Declare the plugin (typically in a plugins.sbt):

addSbtPlugin("com.typesafe.conductr" % "sbt-conductr-sandbox" % "1.0.2")

Then enable the ConductRSandbox plugin for your module. For example:

lazy val root = (project in file(".")).enablePlugins(ConductRSandbox)

To run the sandbox environment use the following command:

sandbox run

Note that the ConductR cluster will take a few seconds to become available and so any initial command that you send to it may not work immediately.

Given the above you will then have a ConductR process running in the background (there will be an initial download cost for Docker to download the image from the public Docker registry).

If the sbt-conductr plugin is enabled for your project then the conduct info and other conduct commands will automatically communicate with the Docker cluster managed by the sandbox.

To enable optional ConductR features for your sandbox specify the --withFeatures option during startup, e.g.:

[my-app] sandbox run --withFeatures visualization logging
[info] Running ConductR...
[info] Running container cond-0 exposing 192.168.59.103:9000 192.168.59.103:9909...

Check out the Features section for more information.

It is possible to debug your application inside of the ConductR sandbox:

1. Start ConductR sandbox in debug mode:

   sandbox debug

2. This exposes a debug port to docker and the ConductR container. By default the debug port is set to 5005 which is the default port for remote debugging in IDEs such as IntelliJ. If you are happy with the default setting skip this step. Otherwise specify another port in the build.sbt:

   SandboxKeys.debugPort := 5432

3. Load and run your bundle to the sandbox, e.g. by using sbt-conductr:

   conduct load <HIT THE TAB KEY AND THEN RETURN>
   conduct run my-app

You should be now able to remotely debug the bundle inside the ConductRs sandbox with your favorite IDE.

To stop the sandbox use:

sandbox stop

ConductR provides additional features which can be optionally enabled:

Each node of the Docker cluster managed by the sandbox is given a name of the form cond-n where n is the node number starting at zero. Thus cond-0 is the first node (and the only node given default settings).

The following ports are exposed to the ConductR and Docker containers:

• BundleKeys.endpoints of sbt-bundle
• SandboxKeys.ports
• SandboxKeys.debugPort if sandbox is started in debug mode

Your application defines these settings in the build.sbt:

lazy val root = (project in file(".")).enablePlugins(ConductRPlugin, ConductRSandbox)

BundleKeys.endpoints := Map("sample-app" -> Endpoint("http", services = Set(uri("http://:9000"))))
SandboxKeys.image in Global := "conductr/conductr"
SandboxKeys.nrOfContainers in Global := 3
SandboxKeys.ports in Global := Set(1111)
SandboxKeys.debugPort := 5095

In this case we want to create a ConductR sandbox cluster with 3 nodes.

Note that a cluster with more than one node is only possible with the full version of ConductR. If SandboxKeys.image is not overridden the single node version will be used.

We also specify that the web application should serve traffic on port 9000. Additionally we expose port 1111. The debug port gets only mapped if we start the ConductR sandbox cluster in debug mode with sandbox debug.

These settings result in the following port mapping:

Each specified port is mapped to a unique public Docker port in order to allow multiple nodes within the sandbox cluster. By convention, the port is mapped for the first Docker container to XX0X, the second will be XX1X, the third will be XX2X. The web application becomes available on the IP addresses of the Docker containers that host each ConductR process. The sandbox cluster is configured with a proxy and will automatically route requests to the correct instances that you have running in the cluster. Therefore any one of the addresses with the 9000, 9010 or 9020 ports will reach your application.

As a convenience, sandbox run and sandbox debug reports each of the above mappings along with IP addresses.

The following settings are provided under the SandboxKeys object:

The following commands are provided:

© Typesafe Inc., 2015