WIP: demo script writing, derp, need a shell script to simplify

doc/dev-clone-compile.md

@@ -14,7 +14,9 @@ to finish.
 
     make test
 
-At the end, the test suite should report that all tests passed.
+At the end, the test suite should report that all tests passed.  The
+actual number of tests shown in the "All `X` tests passed" line may be
+different than the example below.
 
     [... many lines omitted ...]
     module 'event_logger'

doc/dev-prerequisites.md

@@ -1,15 +1,18 @@
 ## Machi developer environment prerequisites
 
-1. Machi requires an OS X, FreeBSD, Linux, or Solaris machine is a
+1. Machi requires an 64-bit variant of UNIX: OS X, FreeBSD, Linux, or
-   standard developer environment for C and C++ applications.
+   Solaris machine is a standard developer environment for C and C++
+   applications (64-bit versions).
 2. You'll need the `git` source management utility.
-3. You'll need the Erlang/OTP 17 runtime environment.  Please don't
+3. You'll need the 64-bit Erlang/OTP 17 runtime environment.  Please
-   use earlier or later versions until we have a chance to fix the
+   don't use earlier or later versions until we have a chance to fix
-   compilation warnings that versions R16B and 18 will trigger.
+   the compilation warnings that versions R16B and 18 will trigger.
+   Also, please verify that you are not using a 32-bit Erlang/OTP
+   runtime package.
 
 For `git` and the Erlang runtime, please use your OS-specific
 package manager to install these.  If your package manager doesn't
-have Erlang/OTP version 17 available, then we recommend using the
+have 64-bit Erlang/OTP version 17 available, then we recommend using the
 [precompiled packages available at Erlang Solutions](https://www.erlang-solutions.com/resources/download.html).
 
 Also, please verify that you have enough file descriptors available to

doc/humming-consensus-demo.md

@@ -33,9 +33,69 @@ Run the following command:
 
 This will create a directory structure like this:
           
-          |-dev1-|... stand-alone Machi app directories
+          |-dev1-|... stand-alone Machi app + subdirectories
-    |-dev-|-dev2-|... stand-alone Machi app directories
+    |-dev-|-dev2-|... stand-alone Machi app + directories
-          |-dev3-|... stand-alone Machi app directories
+          |-dev3-|... stand-alone Machi app + directories
+    
+Each of the `dev/dev1`, `dev/dev2`, and `dev/dev3` are stand-alone
+application instances of Machi and can be run independently of each
+other on the same machine.  This demo will use all three.
+
+The lifecycle management utilities for Machi are a bit immature,
+currently.  They assume that each Machi server runs on a host with a
+unique hostname -- there is no flexibility built-in yet to easily run
+multiple Machi instances on the same machine.  To continue with the
+demo, we need to use `sudo` or `su` to obtain superuser privileges to
+edit the `/etc/hosts` file.
+
+Please add the following line to `/etc/hosts`, using this command:
+
+    sudo sh -c 'echo "127.0.0.1 machi1 machi2 machi3" >> /etc/hosts'
+
+Then please verify that all three new hostnames for the localhost
+network interface are working correctly:
+
+    ping -c 1 machi1 ; ping -c 1 machi2 ; ping -c 1 machi3
+
+If that worked, then we're ready for the next step: starting our three
+Machi app instances on this machine, then configure a single chain to
+to experiment with.
+
+Run the following commands to start the three Machi app instances and
+use the `machi ping` command to verify that all three are running.
+
+    sh -c 'for i in 1 2 3; do ./dev/dev$i/bin/machi start; done
+    sh -c 'for i in 1 2 3; do ./dev/dev$i/bin/machi ping; done
+
+The output from the `ping` commands should be:
+
+    pong
+    pong
+    pong
+
+Next, use the following to configure a single chain:
+
+    sh -c 'for i in 1 2 3; do ./dev/dev$i/bin/machi-admin
+
+The results should be:
+
+    Result: ok
+    Result: ok
+    Result: ok
+
+We have now created a single replica chain, called `c1`, that has
+three file servers participating in the chain.  Thanks to the
+hostnames that we added to `/etc/hosts`, all are using the localhost
+network interface.
+
+    | App instance | Hostname | FLU name | TCP port |
+    | directory    |          |          |   number |
+    |--------------+----------+----------+----------|
+    | dev1         | machi1   | flu1     |    20401 |
+    | dev2         | machi2   | flu2     |    20402 |
+    | dev3         | machi3   | flu3     |    20403 |
+
+The log files for each application instance can be found 
 
 <a name="partition-simulator">
 # Using the network partition simulator and convergence demo test code

priv/quick-admin-examples/demo-000

@@ -0,0 +1,7 @@
+{host, "machi1", []}.
+{host, "machi2", []}.
+{host, "machi3", []}.
+{flu,f1,"machi1",20401,[]}.
+{flu,f2,"machi2",20402,[]}.
+{flu,f3,"machi3",20403,[]}.
+{chain,c1,[f1,f2,f3],[]}.

rel/reltool.config

@@ -106,6 +106,7 @@
            {copy, "../priv/quick-admin-examples/000", "priv/quick-admin-examples"},
            {copy, "../priv/quick-admin-examples/001", "priv/quick-admin-examples"},
            {copy, "../priv/quick-admin-examples/002", "priv/quick-admin-examples"},
+           {copy, "../priv/quick-admin-examples/demo-000", "priv/quick-admin-examples/demo-000"},
 
            {mkdir, "lib/basho-patches"}
            %% {copy, "../apps/machi/ebin/etop_txt.beam", "lib/basho-patches"}