add information about starting a cluster using CrateLayer

CHANGES.txt

@@ -5,8 +5,7 @@ Changes for crate
 Unreleased
 ==========
 
- - add the ``cluster_name`` option to CrateLayer
-   in order to build test clusters using CrateLayer instances
+ - add new options to CrateLayer in order to build test clusters
 
 2014/09/19 0.11.2
 =================

src/crate/testing/layer.py

@@ -26,7 +26,8 @@ def __init__(self,
                  transport_port=None,
                  crate_exec=None,
                  cluster_name=None,
-                 host="localhost"):
+                 host="localhost",
+                 multicast=False):
         """
         :param name: layer name, is also used as the cluser name
         :param crate_home: path to home directory of the crate installation
@@ -58,7 +59,7 @@ def __init__(self,
             '-Des.http.port=%s-%s' % (port, port),
             '-Des.network.host=%s' % host,
             '-Des.discovery.type=zen',
-            '-Des.discovery.zen.ping.multicast.enabled=false',
+            '-Des.discovery.zen.ping.multicast.enabled=%s' % ("true" if multicast else "false"),
             '-Des.config=%s' % crate_config,
             '-Des.path.conf=%s' % os.path.dirname(crate_config),
         )

src/crate/testing/layer.txt

@@ -2,6 +2,9 @@
 Crate Test Layer
 ================
 
+Basic Usage
+-----------
+
 This layer starts and stops a ``Crate`` instance on a given host, port,
 a given crate node name and, optionally, a given cluster name::
 
@@ -20,7 +23,6 @@ a given crate node name and, optionally, a given cluster name::
     ...                     cluster_name='my_cluster'
     ... )
 
-
 The urls of the crate servers to be instantiated can be obtained
 via ``crate_servers``::
 
@@ -53,6 +55,8 @@ The layer can be shutdown using its ``stop()`` method::
 
     >>> layer.stop()
 
+Default Values
+--------------
 
 Starting a ``Crate`` layer leaving out optional parameters will apply the following defaults::
 
@@ -75,4 +79,61 @@ the layer name::
 The command to call is ``bin/crate`` inside the ``crate_home`` path.
 The default config file is ``config/crate.yml`` inside ``crate_home``.
 The default cluster name will be auto generated using the HTTP port.
+If the ``multicast`` argument is omitted the ``Crate`` instance
+will not use multicast to discover other nodes to join a cluster.
+
+
+Starting a Cluster
+------------------
+
+To start a cluster of ``Crate`` instances, give each instance the same
+``cluster_name``, do not use ``localhost`` or any local ip as ``host``,
+give every node different ports if they run on the same machine
+and enable ``multicast``::
+
+    >>> cluster_layer1 = CrateLayer(
+    ...     'crate1',
+    ...     crate_path(),
+    ...     host=public_ip,
+    ...     port=42201,
+    ...     transport_port=43301,
+    ...     cluster_name='my_cluster',
+    ...     multicast=True
+    ... )
+    >>> cluster_layer2 = CrateLayer(
+    ...     'crate2',
+    ...     crate_path(),
+    ...     host=public_ip,
+    ...     port=42202,
+    ...     transport_port=43302,
+    ...     cluster_name='my_cluster',
+    ...     multicast=True
+    ... )
+
+If we start both layers, they will, after a small amount of time, find each other
+and form a cluster::
+
+    >>> cluster_layer1.start()
+    >>> cluster_layer2.start()
+
+We can verify that by checking the number of nodes a node knows about::
+
+    >>> import json
+    >>> def num_cluster_nodes(crate_layer):
+    ...     sql_uri = crate_layer.crate_servers[0] + "/_sql"
+    ...     response = http.urlopen('POST', sql_uri, body='{"stmt":"select count(*) from sys.nodes"}')
+    ...     json_response = json.loads(response.data.decode('utf-8'))
+    ...     return json_response["rows"][0][0]
+
+We might have to wait a moment before the cluster is finally created::
+
+    >>> num_nodes = num_cluster_nodes(cluster_layer1)
+    >>> if num_nodes != 2:
+    ...     import time
+    ...     time.sleep(5)
+    ...     num_nodes = num_cluster_nodes(cluster_layer1)
+    >>> num_nodes
+    2
 
+    >>> cluster_layer1.stop()
+    >>> cluster_layer2.stop()

src/crate/testing/tests.py

@@ -10,10 +10,13 @@ def docs_path(*parts):
 def crate_path(*parts):
     return docs_path('..', '..', 'parts', 'crate', *parts)
 
+def public_ip():
+    import socket
+    return socket.gethostbyname(socket.gethostname())
 
 def setUp(test):
     test.globs['crate_path'] = crate_path
-
+    test.globs['public_ip'] = public_ip()
 
 def test_suite():
     suite = unittest.TestSuite()