Include guide to running on a cluster of nodes

cluster/node1.sys.config

@@ -0,0 +1,6 @@
+[{kernel,
+  [
+    {sync_nodes_optional, ['[email protected]', '[email protected]']},
+    {sync_nodes_timeout, 30000}
+  ]}
+].

cluster/node2.sys.config

@@ -0,0 +1,6 @@
+[{kernel,
+  [
+    {sync_nodes_optional, ['[email protected]', '[email protected]']},
+    {sync_nodes_timeout, 30000}
+  ]}
+].

cluster/node3.sys.config

@@ -0,0 +1,6 @@
+[{kernel,
+  [
+    {sync_nodes_optional, ['[email protected]', '[email protected]']},
+    {sync_nodes_timeout, 30000}
+  ]}
+].

guides/cluster.md

@@ -0,0 +1,63 @@
+# Cluster
+
+### Starting a cluster
+
+1. Run an [Erlang Port Mapper Daemon](http://erlang.org/doc/man/epmd.html) (epmd):
+
+```console
+$ epmd -d
+```
+
+2. Start an `iex` console per node:
+
+```console
+$ MIX_ENV=distributed iex --name [email protected] --erl "-config cluster/node1.sys.config" -S mix
+```
+
+```console
+$ MIX_ENV=distributed iex --name [email protected] --erl "-config cluster/node2.sys.config" -S mix
+```
+
+```console
+$ MIX_ENV=distributed iex --name [email protected] --erl "-config cluster/node3.sys.config" -S mix
+```
+
+The node specific `<node>.sys.config` files ensure the cluster is formed before starting the `:eventstore` application, assuming this occurs within the 30 seconds timeout. Once running, you can use the Event Store API from any node. Stream processes will be distributed amongst the cluster and moved around on node up/down.
+
+### Append events to a stream
+
+```elixir
+stream_uuid = UUID.uuid4()
+events = EventStore.EventFactory.create_events(3)
+
+:ok = EventStore.append_to_stream(stream_uuid, 0, events)
+```
+
+### Read all events
+
+```elixir
+recorded_events = EventStore.stream_all_forward() |> Enum.to_list()
+```
+
+### Subscribe to all Streams
+
+```elixir
+{:ok, subscription} = EventStore.subscribe_to_all_streams("example-subscription", self(), start_from: :origin)
+
+receive do
+  {:events, events} ->
+    IO.puts "Received events: #{inspect events}"
+    EventStore.ack(subscription, events)
+
+  reply ->
+    IO.puts reply
+end
+```
+
+## Cluster diagnostics
+
+Peek into the Swarm process registry:
+
+```elixir
+Swarm.Registry.registered()
+```

mix.exs

@@ -29,7 +29,7 @@ defmodule EventStore.Mixfile do
     ]
   end
 
-  def registry_applications do
+  defp registry_applications do
     case Application.get_env(:eventstore, :registry) do
       :distributed -> [:swarm]
       _ -> []
@@ -101,11 +101,11 @@ EventStore using PostgreSQL for persistence.
   defp test_distributed(args), do: test_registry(:distributed, args)
   defp test_local(args), do: test_registry(:local, args)
   defp test_registry(registry, args) do
-    args = if IO.ANSI.enabled?, do: ["--color"|args], else: ["--no-color"|args]
+    test_args = if IO.ANSI.enabled?, do: ["--color"|args], else: ["--no-color"|args]
 
-    IO.puts "==> Running tests for MIX_ENV=#{registry} mix test"
+    IO.puts "==> Running tests for MIX_ENV=#{registry} mix test #{Enum.join(args, " ")}"
 
-    {_, res} = System.cmd "mix", ["test"|args],
+    {_, res} = System.cmd "mix", ["test"|test_args],
                           into: IO.binstream(:stdio, :line),
                           env: [{"MIX_ENV", to_string(registry)}]