<commit_before>
# Table of contents

* [Hand-on experiments with Machi and Humming Consensus](#hands-on)
* [Using the network partition simulator and convergence demo test code](#partition-simulator)

<a name="hands-on">
# Hand-on experiments with Machi and Humming Consensus

## Prerequisites

Please refer to the
[Machi development environment prerequisites doc](./dev-prerequisites.md)
for Machi developer environment prerequisites.

<a name="clone-compile">
## Clone and compile the code

Please see the
[Machi 'clone and compile' doc](./dev-clone-compile.md)
for the short list of steps required to fetch the Machi source code
from GitHub and to compile &amp; test Machi.

## Running three Machi instances on a single machine

All of the commands that should be run at your login shell (e.g. Bash,
c-shell) can be cut-and-pasted from this document directly to your
login shell prompt.

Run the following command:

    make stagedevrel

This will create a directory structure like this:
          
          |-dev1-|... stand-alone Machi app + subdirectories
    |-dev-|-dev2-|... 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<commit_msg>priv/humming-consensus-demo.setup.sh debugged, all appears to work<commit_after>
# Table of contents

* [Hand-on experiments with Machi and Humming Consensus](#hands-on)
* [Using the network partition simulator and convergence demo test code](#partition-simulator)

<a name="hands-on">
# Hand-on experiments with Machi and Humming Consensus

## Prerequisites

Please refer to the
[Machi development environment prerequisites doc](./dev-prerequisites.md)
for Machi developer environment prerequisites.

<a name="clone-compile">
## Clone and compile the code

Please see the
[Machi 'clone and compile' doc](./dev-clone-compile.md)
for the short list of steps required to fetch the Machi source code
from GitHub and to compile &amp; test Machi.

## Running three Machi instances on a single machine

All of the commands that should be run at your login shell (e.g. Bash,
c-shell) can be cut-and-pasted from this document directly to your
login shell prompt.

Run the following command:

    make stagedevrel

This will create a directory structure like this:
          
          |-dev1-|... stand-alone Machi app + subdirectories
    |-dev-|-dev2-|... 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'

Next, we will use a shell script to finish setting up our cluster.  It
will do the following for us:

* Verify that the new line that was added to `/etc/hosts` is correct.
* Modify the `etc/app.config` files to configure the Humming Consensus
  chain manager's actions logged to the `log/console.log` file.
* Start the three application instances.
* Verify that the three instances are running correctly.
* Configure a single chain, with one FLU server per application
  instance.

Please run this script using this command:

    ./priv/humming-consensus-demo.setup.sh

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
{'fraction_non_alphanumeric': 0.08682634730538923, 'fraction_numerical': 0.014221556886227544, 'mean_word_length': 3.01985559566787, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 13, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '790546', 'n_tokens_mistral': 1972, 'n_tokens_neox': 1846, 'n_words': 899}