Merge pull request #1598 from tendermint/bucky/docs-clean

Bucky/docs clean

Makefile

@@ -193,6 +193,10 @@ build-docker:
 build-linux:
 	GOOS=linux GOARCH=amd64 $(MAKE) build
 
+build-docker-localnode:
+	cd networks/local
+	make
+
 # Run a 4-node testnet locally
 localnet-start: localnet-stop
 	@if ! [ -f build/node0/config/genesis.json ]; then docker run --rm -v $(CURDIR)/build:/tendermint:Z tendermint/localnode testnet --v 4 --o . --populate-persistent-peers --starting-ip-address 192.167.10.2 ; fi
@@ -225,5 +229,5 @@ sentry-stop:
 # To avoid unintended conflicts with file names, always add to .PHONY
 # unless there is a reason not to.
 # https://www.gnu.org/software/make/manual/html_node/Phony-Targets.html
-.PHONY: check build build_race dist install check_tools get_tools update_tools get_vendor_deps draw_deps test_cover test_apps test_persistence test_p2p test test_race test_integrations test_release test100 vagrant_test fmt build-linux localnet-start localnet-stop build-docker sentry-start sentry-config sentry-stop
+.PHONY: check build build_race dist install check_tools get_tools update_tools get_vendor_deps draw_deps test_cover test_apps test_persistence test_p2p test test_race test_integrations test_release test100 vagrant_test fmt build-linux localnet-start localnet-stop build-docker build-docker-localnode sentry-start sentry-config sentry-stop
 

README.md

@@ -24,9 +24,14 @@ _NOTE: This is alpha software. Please contact us if you intend to run it in prod
 Tendermint Core is Byzantine Fault Tolerant (BFT) middleware that takes a state transition machine - written in any programming language -
 and securely replicates it on many machines.
 
-For more information, from introduction to installation and application development, [Read The Docs](https://tendermint.readthedocs.io/en/master/).
+For protocol details, see [the specification](/docs/spec).
 
-For protocol details, see [the specification](./docs/specification/new-spec).
+## Security
+
+To report a security vulnerability, see our [bug bounty
+program](https://tendermint.com/security).
+
+For examples of the kinds of bugs we're looking for, see [SECURITY.md](SECURITY.md)
 
 ## Minimum requirements
 
@@ -36,19 +41,19 @@ Go version | Go1.9 or higher
 
 ## Install
 
-To download pre-built binaries, see our [downloads page](https://tendermint.com/downloads).
+See the [install instructions](/docs/install.rst)
 
-To install from source, you should be able to:
+## Quick Start
 
-`go get -u github.com/tendermint/tendermint/cmd/tendermint`
-
-For more details (or if it fails), [read the docs](https://tendermint.readthedocs.io/en/master/install.html).
+- [Single node](/docs/using-tendermint.rst)
+- [Local cluster using docker-compose](/networks/local)
+- [Remote cluster using terraform and ansible](/networks/remote)
 
 ## Resources
 
 ### Tendermint Core
 
-To use Tendermint, build apps on it, or develop it, [Read The Docs](https://tendermint.readthedocs.io/en/master/).
+For more, [Read The Docs](https://tendermint.readthedocs.io/en/master/).
 Additional information about some - and eventually all - of the sub-projects below, can be found at Read The Docs.
 
 ### Sub-projects

SECURITY.md

@@ -0,0 +1,71 @@
+# Security
+
+As part of our [Coordinated Vulnerability Disclosure
+Policy](https://tendermint.com/security), we operate a bug bounty.
+See the policy for more details on submissions and rewards.
+
+Here is a list of examples of the kinds of bugs we're most interested in:
+
+## Specification
+
+- Conceptual flaws
+- Ambiguities, inconsistencies, or incorrect statements
+- Mis-match between specification and implementation of any component
+
+## Consensus
+
+Assuming less than 1/3 of the voting power is Byzantine (malicious):
+
+- Validation of blockchain data structures, including blocks, block parts,
+  votes, and so on
+- Execution of blocks
+- Validator set changes
+- Proposer round robin
+- Two nodes committing conflicting blocks for the same height (safety failure)
+- A correct node signing conflicting votes
+- A node halting (liveness failure)
+- Syncing new and old nodes
+
+## Networking
+
+- Authenticated encryption (MITM, information leakage)
+- Eclipse attacks
+- Sybil attacks
+- Long-range attacks
+- Denial-of-Service
+
+## RPC
+
+- Write-access to anything besides sending transactions
+- Denial-of-Service
+- Leakage of secrets
+
+## Denial-of-Service
+
+Attacks may come through the P2P network or the RPC:
+
+- Amplification attacks
+- Resource abuse
+- Deadlocks and race conditions
+- Panics and unhandled errors
+
+## Libraries
+
+- Serialization (Amino)
+- Reading/Writing files and databases
+- Logging and monitoring
+
+## Cryptography
+
+- Elliptic curves for validator signatures
+- Hash algorithms and Merkle trees for block validation
+- Authenticated encryption for P2P connections
+
+## Light Client
+
+- Validation of blockchain data structures
+- Correctly validating an incorrect proof
+- Incorrectly validating a correct proof
+- Syncing validator set changes
+
+

docs/spec/README.md

@@ -10,12 +10,17 @@ please submit them to our [bug bounty](https://tendermint.com/security)!
 
 ## Contents
 
+- [Overview](#overview)
+
 ### Data Structures
 
-- [Overview](#overview)
-- [Encoding and Digests](encoding.md)
-- [Blockchain](blockchain.md)
-- [State](state.md)
+- [Encoding and Digests](./blockchain/encoding.md)
+- [Blockchain](./blockchain/blockchain.md)
+- [State](./blockchain/state.md)
+
+### Consensus Protocol
+
+- TODO
 
 ### P2P and Network Protocols
 

docs/specification/new-spec/README.md

@@ -1 +1 @@
-Spec moved to [docs/spec](./docs/spec).
+Spec moved to [docs/spec](/docs/spec).

docs/using-tendermint.rst

@@ -28,8 +28,11 @@ genesis file (``genesis.json``) containing the associated public key,
 in ``$TMHOME/config``.
 This is all that's necessary to run a local testnet with one validator.
 
-For more elaborate initialization, see our `testnet deployment
-tool <https://github.com/tendermint/tools/tree/master/mintnet-kubernetes>`__.
+For more elaborate initialization, see the `tesnet` command:
+
+::
+
+    tendermint testnet --help
 
 Run
 ---

networks/local/README.md

@@ -0,0 +1,79 @@
+# Local Cluster with Docker Compose
+
+## Requirements
+
+- [Install tendermint](/docs/install.rst)
+- [Install docker](https://docs.docker.com/engine/installation/)
+- [Install docker-compose](https://docs.docker.com/compose/install/)
+
+## Build
+
+Build the `tendermint` binary and the `tendermint/localnode` docker image.
+
+Note the binary will be mounted into the container so it can be updated without
+rebuilding the image.
+
+```
+cd $GOPATH/src/github.com/tendermint/tendermint
+
+# Build the linux binary in ./build
+make build-linux
+
+# Build tendermint/localnode image
+make build-docker-localnode
+```
+
+
+## Run a testnet
+
+To start a 4 node testnet run:
+
+```
+make localnet-start
+```
+
+The nodes bind their RPC servers to ports 46657, 46660, 46662, and 46664 on the host.
+This file creates a 4-node network using the localnode image.
+The nodes of the network expose their P2P and RPC endpoints to the host machine on ports 46656-46657, 46659-46660, 46661-46662, and 46663-46664 respectively.
+
+To update the binary, just rebuild it and restart the nodes:
+
+```
+make build-linux
+make localnet-stop
+make localnet-start
+```
+
+## Configuration
+
+The `make localnet-start` creates files for a 4-node testnet in `./build` by calling the `tendermint testnet` command.
+
+The `./build` directory is mounted to the `/tendermint` mount point to attach the binary and config files to the container.
+
+For instance, to create a single node testnet:
+
+```
+cd $GOPATH/src/github.com/tendermint/tendermint
+
+# Clear the build folder
+rm -rf ./build
+
+# Build binary
+make build-linux
+
+# Create configuration
+docker run -e LOG="stdout" -v `pwd`/build:/tendermint tendermint/localnode testnet --o . --v 1
+
+#Run the node
+docker run -v `pwd`/build:/tendermint tendermint/localnode
+
+```
+
+## Logging
+
+Log is saved under the attached volume, in the `tendermint.log` file. If the `LOG` environment variable is set to `stdout` at start, the log is not saved, but printed on the screen.
+
+## Special binaries
+
+If you have multiple binaries with different names, you can specify which one to run with the BINARY environment variable. The path of the binary is relative to the attached volume.
+

networks/local/README.rst

@@ -1,40 +0,0 @@
-localnode
-=========
-
-It is assumed that you have already `setup docker <https://docs.docker.com/engine/installation/>`__.
-
-Description
------------
-Image for local testnets.
-
-Add the tendermint binary to the image by attaching it in a folder to the `/tendermint` mount point.
-
-It assumes that the configuration was created by the `tendermint testnet` command and it is also attached to the `/tendermint` mount point.
-
-Example:
-This example builds a linux tendermint binary under the `build/` folder, creates tendermint configuration for a single-node validator and runs the node:
-```
-cd $GOPATH/src/github.com/tendermint/tendermint
-
-#Build binary
-make build-linux
-
-#Create configuration
-docker run -e LOG="stdout" -v `pwd`/build:/tendermint tendermint/localnode testnet --o . --v 1
-
-#Run the node
-docker run -v `pwd`/build:/tendermint tendermint/localnode
-```
-
-Logging
--------
-Log is saved under the attached volume, in the `tendermint.log` file. If the `LOG` environment variable is set to `stdout` at start, the log is not saved, but printed on the screen.
-
-Special binaries
-----------------
-If you have multiple binaries with different names, you can specify which one to run with the BINARY environment variable. The path of the binary is relative to the attached volume.
-
-docker-compose.yml
-==================
-This file creates a 4-node network using the localnode image. The nodes of the network are exposed to the host machine on ports 46656-46657, 46659-46660, 46661-46662, 46663-46664 respectively.
-

networks/remote/README.md

@@ -0,0 +1 @@
+# Remote Cluster with Terraform and Ansible