add quick start guide (#1069)

docs/examples/getting-started.md

@@ -0,0 +1,139 @@
+# Tendermint
+
+## Overview
+
+This is a quick start guide. If you have a vague idea about how Tendermint works
+and want to get started right away, continue. Otherwise, [review the documentation](http://tendermint.readthedocs.io/en/master/)
+
+## Install
+
+### Quick Install
+
+On a fresh Ubuntu 16.04 machine can be done with [this script](https://git.io/vNLfY), like so:
+
+```
+curl -L https://git.io/vNLfY | bash
+source ~/.profile
+```
+
+WARNING: do not run the above on your local machine.
+
+The script is also used to facilitate cluster deployment below.
+
+### Manual Install
+
+Requires: 
+- `go` minimum version 1.9.2
+- `$GOPATH` set and `$GOPATH/bin` on your $PATH (see https://github.com/tendermint/tendermint/wiki/Setting-GOPATH)
+
+To install Tendermint, run:
+
+```
+go get github.com/tendermint/tendermint
+cd $GOPATH/src/github.com/tendermint/tendermint
+make get_vendor_deps
+make install
+```
+
+Confirm installation:
+
+```
+$ tendermint version
+0.15.0-381fe19
+```
+
+## Initialization
+
+Running:
+
+```
+tendermint init
+```
+
+will create the required files for a single, local node.
+
+These files are found in `$HOME/.tendermint`:
+
+```
+$ ls $HOME/.tendermint
+
+config.toml  data  genesis.json  priv_validator.json
+```
+
+For a single, local node, no further configuration is required.
+Configuring a cluster is covered further below.
+
+## Local Node
+
+Start tendermint with a simple in-process application:
+
+```
+tendermint node --proxy_app=dummy
+```
+
+and blocks will start to stream in:
+
+```
+I[01-06|01:45:15.592] Executed block                               module=state height=1 validTxs=0 invalidTxs=0
+I[01-06|01:45:15.624] Committed state                              module=state height=1 txs=0 appHash=
+```
+
+Check the status with:
+
+```
+curl -s localhost:46657/status
+```
+
+### Sending Transactions
+
+With the dummy app running, we can send transactions:
+
+```
+curl -s 'localhost:46657/broadcast_tx_commit?tx="abcd"'
+```
+
+and check that it worked with:
+
+```
+curl -s 'localhost:46657/abci_query?data="abcd"'
+```
+
+We can send transactions with a key:value store:
+
+```
+curl -s 'localhost:46657/broadcast_tx_commit?tx="name=satoshi"'
+```
+
+and query the key:
+
+```
+curl -s 'localhost:46657/abci_query?data="name"'
+```
+
+where the value is returned in hex.
+
+## Cluster of Nodes
+
+First create four Ubuntu cloud machines. The following was testing on Digital Ocean Ubuntu 16.04 x64 (3GB/1CPU, 20GB SSD). We'll refer to their respective IP addresses below as IP1, IP2, IP3, IP4.
+
+Then, `ssh` into each machine, and `curl` then execute [this script](https://git.io/vNLfY):
+
+```
+curl -L https://git.io/vNLfY | bash
+source ~/.profile
+```
+
+This will install `go` and other dependencies, get the Tendermint source code, then compile the `tendermint` binary.
+
+Next, `cd` into `docs/examples`. Each command below should be run from each node, in sequence:
+
+```
+tendermint node --home ./node1 --proxy_app=dummy
+tendermint node --home ./node2 --proxy_app=dummy --p2p.seeds IP1:46656
+tendermint node --home ./node3 --proxy_app=dummy --p2p.seeds IP1:46656,IP2:46656
+tendermint node --home ./node4 --proxy_app=dummy --p2p.seeds IP1:46656,IP2:46656,IP3:46656
+```
+
+Note that after the third node is started, blocks will start to stream in because >2/3 of validators (defined in the `genesis.json` have come online). Seeds can also be specified in the `config.toml`. See [this PR](https://github.com/tendermint/tendermint/pull/792) for more information about configuration options.
+
+Transactions can then be sent as covered in the single, local node example above.

docs/examples/install_tendermint.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+
+# XXX: this script is meant to be used only on a fresh Ubuntu 16.04 instance
+# and has only been tested on Digital Ocean
+
+# get and unpack golang
+curl -O https://storage.googleapis.com/golang/go1.9.2.linux-amd64.tar.gz
+tar -xvf go1.9.2.linux-amd64.tar.gz
+
+apt install make
+
+## move go and add binary to path
+mv go /usr/local
+echo "export PATH=\$PATH:/usr/local/go/bin" >> ~/.profile
+
+## create the GOPATH directory, set GOPATH and put on PATH
+mkdir goApps
+echo "export GOPATH=/root/goApps" >> ~/.profile
+echo "export PATH=\$PATH:\$GOPATH/bin" >> ~/.profile
+
+source ~/.profile
+
+## get the code and move into it
+REPO=github.com/tendermint/tendermint
+go get $REPO
+cd $GOPATH/src/$REPO
+
+## build
+git checkout v0.15.0
+make get_tools
+make get_vendor_deps
+make install

docs/examples/node1/config.toml

@@ -0,0 +1,15 @@
+# This is a TOML config file.
+# For more information, see https://github.com/toml-lang/toml
+
+proxy_app = "tcp://127.0.0.1:46658"
+moniker = "penguin"
+fast_sync = true
+db_backend = "leveldb"
+log_level = "state:info,*:error"
+
+[rpc]
+laddr = "tcp://0.0.0.0:46657"
+
+[p2p]
+laddr = "tcp://0.0.0.0:46656"
+seeds = ""

docs/examples/node1/genesis.json

@@ -0,0 +1,42 @@
+{
+	"genesis_time":"0001-01-01T00:00:00Z",
+	"chain_id":"test-chain-wt7apy",
+	"validators":[
+		{
+			"pub_key":{
+				"type":"ed25519",
+				"data":"F08446C80A33E10D620E21450821B58D053778528F2B583D423B3E46EC647D30"
+			},
+			"power":10,
+			"name":"node1"
+		}
+		,
+		{
+			"pub_key":{
+				"type":"ed25519",
+				"data": "A8423F70A9E512643B4B00F7C3701ECAD1F31B0A1FAA45852C41046353B9A07F"
+			},
+			"power":10,
+			"name":"node2"
+		}
+		,
+		{
+			"pub_key":{
+				"type":"ed25519",
+				"data": "E52EFFAEDFE1D618ECDA71DE3B23592B3612CAABA0C10826E4C3120B2198C29A"
+			},
+			"power":10,
+			"name":"node3"
+		}
+		,
+		{
+			"pub_key":{
+				"type":"ed25519",
+				"data": "2B8FC09C07955A02998DFE5AF1AAD1C44115ECA7635FF51A867CF4265D347C07"
+			},
+			"power":10,
+			"name":"node4"
+		}
+	],
+	"app_hash":""
+}

docs/examples/node1/priv_validator.json

@@ -0,0 +1,15 @@
+{
+	"address":"4DC2756029CE0D8F8C6C3E4C3CE6EE8C30AF352F",
+	"pub_key":{
+		"type":"ed25519",
+		"data":"F08446C80A33E10D620E21450821B58D053778528F2B583D423B3E46EC647D30"
+	},
+	"last_height":0,
+	"last_round":0,
+	"last_step":0,
+	"last_signature":null,
+	"priv_key":{
+		"type":"ed25519",
+		"data":"4D3648E1D93C8703E436BFF814728B6BD270CFDFD686DF5385E8ACBEB7BE2D7DF08446C80A33E10D620E21450821B58D053778528F2B583D423B3E46EC647D30"
+	}
+}

docs/examples/node2/config.toml

@@ -0,0 +1,15 @@
+# This is a TOML config file.
+# For more information, see https://github.com/toml-lang/toml
+
+proxy_app = "tcp://127.0.0.1:46658"
+moniker = "penguin"
+fast_sync = true
+db_backend = "leveldb"
+log_level = "state:info,*:error"
+
+[rpc]
+laddr = "tcp://0.0.0.0:46657"
+
+[p2p]
+laddr = "tcp://0.0.0.0:46656"
+seeds = ""

docs/examples/node2/genesis.json

@@ -0,0 +1,42 @@
+{
+	"genesis_time":"0001-01-01T00:00:00Z",
+	"chain_id":"test-chain-wt7apy",
+	"validators":[
+		{
+			"pub_key":{
+				"type":"ed25519",
+				"data":"F08446C80A33E10D620E21450821B58D053778528F2B583D423B3E46EC647D30"
+			},
+			"power":10,
+			"name":"node1"
+		}
+		,
+		{
+			"pub_key":{
+				"type":"ed25519",
+				"data": "A8423F70A9E512643B4B00F7C3701ECAD1F31B0A1FAA45852C41046353B9A07F"
+			},
+			"power":10,
+			"name":"node2"
+		}
+		,
+		{
+			"pub_key":{
+				"type":"ed25519",
+				"data": "E52EFFAEDFE1D618ECDA71DE3B23592B3612CAABA0C10826E4C3120B2198C29A"
+			},
+			"power":10,
+			"name":"node3"
+		}
+		,
+		{
+			"pub_key":{
+				"type":"ed25519",
+				"data": "2B8FC09C07955A02998DFE5AF1AAD1C44115ECA7635FF51A867CF4265D347C07"
+			},
+			"power":10,
+			"name":"node4"
+		}
+	],
+	"app_hash":""
+}

docs/examples/node2/priv_validator.json

@@ -0,0 +1,15 @@
+{
+	"address": "DD6C63A762608A9DDD4A845657743777F63121D6",
+	"pub_key": {
+		"type": "ed25519",
+		"data": "A8423F70A9E512643B4B00F7C3701ECAD1F31B0A1FAA45852C41046353B9A07F"
+	},
+	"last_height": 0,
+	"last_round": 0,
+	"last_step": 0,
+	"last_signature": null,
+	"priv_key": {
+		"type": "ed25519",
+		"data": "7B0DE666FF5E9B437D284BCE767F612381890C018B93B0A105D2E829A568DA6FA8423F70A9E512643B4B00F7C3701ECAD1F31B0A1FAA45852C41046353B9A07F"
+	}
+}

docs/examples/node3/config.toml

@@ -0,0 +1,15 @@
+# This is a TOML config file.
+# For more information, see https://github.com/toml-lang/toml
+
+proxy_app = "tcp://127.0.0.1:46658"
+moniker = "penguin"
+fast_sync = true
+db_backend = "leveldb"
+log_level = "state:info,*:error"
+
+[rpc]
+laddr = "tcp://0.0.0.0:46657"
+
+[p2p]
+laddr = "tcp://0.0.0.0:46656"
+seeds = ""

docs/examples/node3/genesis.json

@@ -0,0 +1,42 @@
+{
+	"genesis_time":"0001-01-01T00:00:00Z",
+	"chain_id":"test-chain-wt7apy",
+	"validators":[
+		{
+			"pub_key":{
+				"type":"ed25519",
+				"data":"F08446C80A33E10D620E21450821B58D053778528F2B583D423B3E46EC647D30"
+			},
+			"power":10,
+			"name":"node1"
+		}
+		,
+		{
+			"pub_key":{
+				"type":"ed25519",
+				"data": "A8423F70A9E512643B4B00F7C3701ECAD1F31B0A1FAA45852C41046353B9A07F"
+			},
+			"power":10,
+			"name":"node2"
+		}
+		,
+		{
+			"pub_key":{
+				"type":"ed25519",
+				"data": "E52EFFAEDFE1D618ECDA71DE3B23592B3612CAABA0C10826E4C3120B2198C29A"
+			},
+			"power":10,
+			"name":"node3"
+		}
+		,
+		{
+			"pub_key":{
+				"type":"ed25519",
+				"data": "2B8FC09C07955A02998DFE5AF1AAD1C44115ECA7635FF51A867CF4265D347C07"
+			},
+			"power":10,
+			"name":"node4"
+		}
+	],
+	"app_hash":""
+}

docs/examples/node3/priv_validator.json

@@ -0,0 +1,15 @@
+{
+	"address": "6D6A1E313B407B5474106CA8759C976B777AB659",
+	"pub_key": {
+		"type": "ed25519",
+		"data": "E52EFFAEDFE1D618ECDA71DE3B23592B3612CAABA0C10826E4C3120B2198C29A"
+	},
+	"last_height": 0,
+	"last_round": 0,
+	"last_step": 0,
+	"last_signature": null,
+	"priv_key": {
+		"type": "ed25519",
+		"data": "622432A370111A5C25CFE121E163FE709C9D5C95F551EDBD7A2C69A8545C9B76E52EFFAEDFE1D618ECDA71DE3B23592B3612CAABA0C10826E4C3120B2198C29A"
+	}
+}

docs/examples/node4/config.toml

@@ -0,0 +1,15 @@
+# This is a TOML config file.
+# For more information, see https://github.com/toml-lang/toml
+
+proxy_app = "tcp://127.0.0.1:46658"
+moniker = "penguin"
+fast_sync = true
+db_backend = "leveldb"
+log_level = "state:info,*:error"
+
+[rpc]
+laddr = "tcp://0.0.0.0:46657"
+
+[p2p]
+laddr = "tcp://0.0.0.0:46656"
+seeds = ""

docs/examples/node4/genesis.json

@@ -0,0 +1,42 @@
+{
+	"genesis_time":"0001-01-01T00:00:00Z",
+	"chain_id":"test-chain-wt7apy",
+	"validators":[
+		{
+			"pub_key":{
+				"type":"ed25519",
+				"data":"F08446C80A33E10D620E21450821B58D053778528F2B583D423B3E46EC647D30"
+			},
+			"power":10,
+			"name":"node1"
+		}
+		,
+		{
+			"pub_key":{
+				"type":"ed25519",
+				"data": "A8423F70A9E512643B4B00F7C3701ECAD1F31B0A1FAA45852C41046353B9A07F"
+			},
+			"power":10,
+			"name":"node2"
+		}
+		,
+		{
+			"pub_key":{
+				"type":"ed25519",
+				"data": "E52EFFAEDFE1D618ECDA71DE3B23592B3612CAABA0C10826E4C3120B2198C29A"
+			},
+			"power":10,
+			"name":"node3"
+		}
+		,
+		{
+			"pub_key":{
+				"type":"ed25519",
+				"data": "2B8FC09C07955A02998DFE5AF1AAD1C44115ECA7635FF51A867CF4265D347C07"
+			},
+			"power":10,
+			"name":"node4"
+		}
+	],
+	"app_hash":""
+}

docs/examples/node4/priv_validator.json

@@ -0,0 +1,15 @@
+{
+	"address": "829A9663611D3DD88A3D84EA0249679D650A0755",
+	"pub_key": {
+		"type": "ed25519",
+		"data": "2B8FC09C07955A02998DFE5AF1AAD1C44115ECA7635FF51A867CF4265D347C07"
+	},
+	"last_height": 0,
+	"last_round": 0,
+	"last_step": 0,
+	"last_signature": null,
+	"priv_key": {
+		"type": "ed25519",
+		"data": "0A604D1C9AE94A50150BF39E603239092F9392E4773F4D8F4AC1D86E6438E89E2B8FC09C07955A02998DFE5AF1AAD1C44115ECA7635FF51A867CF4265D347C07"
+	}
+}