Skip to content
This repository has been archived by the owner on Jul 9, 2020. It is now read-only.

jake-review-simple-install #60

Open
wants to merge 2 commits into
base: develop
Choose a base branch
from
Open

jake-review-simple-install #60

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
97c9ed8
Update simple-install.md
JakeSCahill Dec 10, 2018
bb17a67
Format code snippets
JakeSCahill Dec 11, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
164 changes: 110 additions & 54 deletions pages/compass/quick-start/simple-install.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,88 +12,119 @@ editUrl: 'pages/compass/quick-start/simple-install.md',

export default withRouter(props => WithMDX(props, page))

In this guide we will set up a minimal private tangle with a single IRI node and a Compass coordinator issuing milestones. After you complete this tutorial you should be able to interact with your private tangle using your favorite IOTA tools and libraries.

In this guide, we set up a private IOTA network that includes the following components:
* A single IRI node
* A Compass Coordinator (Compass) that sends milestone transactions to the IRI node

For this basic setup we install both the IRI node and Compass on the same computer.

After you complete this tutorial you will be able to interact with your private IOTA network using your favorite tools and libraries.

## Requirements

For this basic setup we will install both the IRI node and the Compass coordinator on the same server/virtual machine. This is what you need:
* To run Compass, your computer must meet the following minimum requirements:

- A Freshly installed Ubuntu 18.04 Server / Virtual Machine
- At least 8GB RAM
- Preferably 4+ CPU cores, the more cores the faster the Merkle tree will generate.
- At least a 10GB SSD
* A Ubuntu 18.04 Server or a virtual machine
* At least 8GB RAM
* Preferably 4 or more CPU cores. The more CPU cores, the faster the Merkle tree will be generated.
* At least a 10GB SSD

## Setting up the dependencies

Compass uses [Bazel](https://bazel.build/) to build and [Docker](https://www.docker.com/) to run, so we need to make sure both are installed.
First we install the dependencies we need for Bazel to install:
Compass needs [Bazel](https://bazel.build/) to be built and [Docker](https://www.docker.com/) to be run, so make sure that both are installed on your computer.

1. Install the Bazel dependencies:

```bash
sudo apt-get install pkg-config zip g++ zlib1g-dev unzip python
```


Next we retrieve the latest installer for Bazel:

2. Download the latest Bazel installer:
```bash
wget https://github.com/bazelbuild/bazel/releases/download/0.18.0/bazel-0.18.0-installer-linux-x86_64.sh
```

Next we need to make sure we can execute this script before we can actually run it:

3. Execute this script:

```bash
chmod +x bazel-0.18.0-installer-linux-x86_64.sh
```

After doing this we can install Bazel, we will install it under your currently active user using the `--user` flag:

4. Install Bazel under the current active user, using the `--user` flag:

```bash
./bazel-0.18.0-installer-linux-x86_64.sh --user
```

Now that Bazel is installed we need to install Docker:

5. Install Docker:

```bash
sudo apt install apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu bionic stable"
sudo apt update
sudo apt install docker-ce
```

After installing Docker we need to make sure we have a tool called `jq` as well, this tool can be found in the Ubuntu universe repository so we'll add that first:
6. Install the jq tool:

```bash
sudo apt install curl jq
```

sudo add-apt-repository universe
sudo apt install jq
**Note:** The jq tool is a command-line JSON processor that helps you to display and manipulate JSON data. This tool is optional.

This is all we need to get started.
## Creating the milestone Merkle tree

## Calculating the Milestone Merkle tree
Before you can set up Compass, you need to generate a [Merkle tree](https://en.wikipedia.org/wiki/Merkle_tree). This Merkle tree make sure that every milestone has the Compass's fixed address as its root, which is known by each IRI node in your private IOTA network. This way, the IRI can validate a milestone by finding the root of the Merkle tree and comparing it to the Compass's fixed address. Only a valid Compass has the correct seed that can create valid milestones on your IOTA network.

Before we can start on our Coordinator setup we need to generate a [Merkle tree](https://en.wikipedia.org/wiki/Merkle_tree). This tree will make sure every milestone created by Compass references back to the fixed address of the Coordinator known by every IRI instance in your tangle (in this example just a single node). This way only the Compass coordinator with the right seed can issue valid milestones for this tangle. The Compass repository includes a simple tool to generate this Merkle tree.
The amount of milestones that Compass can send is based on the depth of the Merkle tree. For example, a depth of 16 creates a Merkle tree that has 2<sup>16</sup> leaf nodes, resulting in a maximum of 65536 milestones. In this example, if Compass were to send milestones every minute, it would be able to run 2<sup>depth</sup> minutes before it ran out of milestones.

First we need to clone the GitHub repo for Compass:
**Note:** The greater the depth, the longer it takes to generate the Merkle tree. For this guide, we use a depth of 16, which allows us to run Compass for 45 consecutive days at 1-minute milestone intervals. Calculating the Merkle tree for this depth will not take long. For a comparison, a depth of 24 would allow you to run Compass for over 31 years but it would take a lot of CPU hours to generate the Merkle tree. Whereas, a depth of 8 would allow you to run Compass for only a couple of hours, and will take a couple of seconds to generate the Merkle tree

1. Clone the GitHub repo for Compass:

```bash
git clone https://github.com/iotaledger/compass.git
cd compass
```

Next up we need to build the layers_calculator tool that will generate the Merkle tree for us:
2. Build the layers_calculator tool that will generate the Merkle tree:

```bash
bazel run //docker:layers_calculator
```

Next we need to think of a depth for our Merkle tree. In order to use the tree we need to calculate all possible branches for this tree first, the 'deeper' we go the more branches we will have. The amount of milestones you can issue is based on the simple formula of 2<sup>depth</sup>, so a depth of 16 is 2<sup>16</sup> resulting in a maximum of 65536 milestones, if you issue milestones every minute you can run 2<sup>depth</sup> minutes before you run out of milestones to issue, so the depth needs to be high enough for your test to complete. On the other hand the higher the depth the longer the tree generation takes. For our demo purpose we'll use a depth of 16, this allows us to run compass for 45 days in a row at 1 minute milestone intervals. Calculating the tree for this will not take as long. For comparison: A depth of 24 would allow you to run Compass for over 31 years but it will take a lot of CPU hours to generate that tree. If you don't want to wait 15-30 minutes for the tree to generate you can choose to go for a depth of 8 as well, this will only take a couple of seconds to generate but you will only be able to run your coordinator for a couple of hours before you run out of milestones.

First we need to generate a new seed for our coordinator, we do that using the following command:
2. Generate a new seed for your Compass:

cat /dev/urandom |LC_ALL=C tr -dc 'A-Z9' | fold -w 81 | head -n 1
```bash
cat /dev/urandom |LC_ALL=C tr -dc 'A-Z9' | fold -w 81 | head -n 1
```

Copy the result of this command, we will add it to our configuration file in a moment.
Copy the output of this command. You'll need to paste it into your configuration file (config.json) in step 4.

The Compass repository comes with a set of scripts to make it easier for us to get this setup up and running. Let's check it out:
3. The Compass repository includes scripts that make it easier for you to start your Compass:

```bash
cd docs/private_tangle
```

In this folder there is a example configuration file, let's copy it before we edit it:
4. In this directory, copy the example configuration file:

```bash
cp config.example.json config.json
```

Open the `config.json` file in your favorite editor and replace the seed with the seed you generated.
5. Open the `config.json` file in your favorite editor and replace the seed with the seed you generated in step 1:

```bash
nano config.json
```

You should replace the `depth` parameter as well with the depth you want to generate a Merkle tree for (in our example we change it to `16`). The finished `config.json` should look like this:
6. Replace the `depth` parameter with your chosen depth (in our example we change it to 16). Your `config.json` file should look something like this:

```json
{
"seed": "MYSEEDHEREPLEASEREPLACEMEIMMEDIATELYWITHSOMETHINGSECURE99999999999999999999999999",
"powMode": "CURLP81",
Expand All @@ -105,58 +136,83 @@ You should replace the `depth` parameter as well with the depth you want to gene
"tick": 60000,
"host": "http://localhost:14265"
}
```

We need to make sure Docker is aware of the layers_calculator image, let's run it first:
7. Make sure that Docker is aware of the layers_calculator image:

```bash
sudo ../../bazel-bin/docker/layers_calculator
```

Now we are ready to generate our Merkle tree, to do this we execute the script in `docs/private_tangle`:
8. Generate the Merkle tree by executing the script in the `docs/private_tangle` directory:

```bash
sudo ./01_calculate_layers.sh
```

This process will take a while (with a 4 core virtual machine it took around 15 minutes with a depth of 16), after it is done it should tell you what the root of your tree is:
This process will take a while (with a 4 core virtual machine it took around 15 minutes with a depth of 16), after the Merkle tree has been generated, the root should be printed to the console output:

[main] INFO org.iota.compass.LayersCalculator - Calculating 65536 addresses.
...
[main] INFO org.iota.compass.LayersCalculator - Successfully wrote Merkle Tree with root: JMRTYHMGNZGNOLPSSBVLWRPMGIAMOXPLURNDIBKXIFTCJCLOYKH9FMVNKPBVFVMGSUFEYVUUIEARFQXAK
```shell
[main] INFO org.iota.compass.LayersCalculator - Calculating 65536 addresses.
...
[main] INFO org.iota.compass.LayersCalculator - Successfully wrote Merkle Tree with root: JMRTYHMGNZGNOLPSSBVLWRPMGIAMOXPLURNDIBKXIFTCJCLOYKH9FMVNKPBVFVMGSUFEYVUUIEARFQXAK
```

This script stores your tree in the data folder so Compass will use it once we run it.
This script stores your Merkle tree in the data directory for Compass to access.

## Run IRI
## Running the IRI

Now we need our first IRI node to run before we can turn on Compass, this is a pretty straightforward process and we have a script for this as well taking our generated Merkle tree root into account. This script actually uses the default IRI Docker container with some additional parameters. Our IRI node works with a snapshot file to set the initial state of the tangle, we will keep it simple here and we will put the total IOTA supply of 2.7Pi in the first address generated by the seed `SEED99999999999999999999999999999999999999999999999999999999999999999999999999999`; This is `FJHSSHBZTAKQNDTIKJYCZBOZDGSZANCZSWCNWUOCZXFADNOQSYAHEJPXRLOVPNOQFQXXGEGVDGICLMOXX` (Excluding the address checksum). Open up the new file `snapshot.txt` in your favorite editor:
Before you can run Compass, you need to run the IRI. this is a pretty straightforward process and we have a script for this as well taking our generated Merkle tree root into account. This script uses the default IRI Docker container with some additional parameters. The IRI node uses a snapshot file to set the initial state of the ledger.

1. Create and open the snapshot.txt file:

```bash
nano snapshot.txt
```

And add the following line:

2. Add the following to the file. The characters on the left of the semicolon are an IOTA address (public key). The number on the right of the semicolon is the amount of IOTAs in the address (the maximum supply).

```shell
FJHSSHBZTAKQNDTIKJYCZBOZDGSZANCZSWCNWUOCZXFADNOQSYAHEJPXRLOVPNOQFQXXGEGVDGICLMOXX;2779530283277761
```

Please do not exceed this maximum supply, it might not work if you do that, allocating less should not be a problem.
**Note:** Don't exceed the maximum supply, the IRI might not work if you do.

That's all we need to do for now, let's fire up IRI!
3. Run the IRI:

```bash
sudo ./02_run_iri.sh
```

If everything went right you should see IRI starting up now. You can use `CTRL+C` in the console to go back to your shell session, IRI will continue to run in the background.
In the console output, you should see that the IRI is outputting data. You can use CTRL+C in the console to go back to your shell session. The IRI will continue to run in the background.

## Running Compass

After we generated the Merkle tree and installed IRI we can finally start our coordinator. But we need to build it first using bazel. Go back to your `compass` directory and run bazel:
After you've generated the Merkle tree and installed IRI, you can run Compass.

1. Build Compass in your compass directory:

```bash
cd ~/compass/
bazel run //docker:coordinator
```

Next we need to run the Docker container for a first time:
2. Run the Docker container:

```bash
sudo ../../bazel-bin/docker/coordinator
```

Now we are ready to run the coordinator
3. Run Compass:

```bash
sudo ./03_run_coordinator.sh -bootstrap -broadcast
```

In the console output, you should see that Compass is issuing milestones. Great! You have a private IOTA network!

The logs should tell you it is issuing milestones; Great! We should now have a functional private tangle to tinker with! Please note that the coordinator will stop working if you run out of calculated milestones, don't use a too low depth or you might have to start over again soon.
**Note:** Compass will stop working if it runs out of milestones. To avoid running out of milestones, you should specify a greater `depth` parameter when [creating the milestone Merkle tree](#creating-the-milestone-merkle-tree).

## Testing your network

You should be able to connect to your IRI node with your favorite software on port 14265, This can be a wallet or a client library. Once you are connected to a your node and entered the `SEED99999999999999999999999999999999999999999999999999999999999999999999999999999` seed you should be able to see the complete 2.7Pi allocated (you might have to manually attach the first address depending on what client library/wallet you are using). Feel free to send over test transactions and see them confirmed by the coordinator.
Connect to your IRI node on port 14265 by using a client such as the Trinity wallet or a client library. After your client is connected to the IRI node, try interacting with the IRI through the [REST API](https://iota.readme.io/reference).