From 63e2f43b72021933a4895fa34601f6ec18f7a271 Mon Sep 17 00:00:00 2001 From: Zach Date: Wed, 20 Jun 2018 03:51:16 -0400 Subject: [PATCH] updates to docs for vuepress (#1763) * fix docs for vue, #1640 * docs: clean up re-install instructions --- docs/ecosystem.md | 2 +- docs/install.md | 76 +++++++++++ docs/install.rst | 99 -------------- docs/specification/configuration.md | 189 ++++++++++++++++++++++++++ docs/specification/configuration.rst | 191 --------------------------- docs/specification/rpc.md | 3 + docs/specification/rpc.rst | 4 - docs/terraform-and-ansible.md | 85 +++++++----- 8 files changed, 322 insertions(+), 327 deletions(-) create mode 100644 docs/install.md delete mode 100644 docs/install.rst create mode 100644 docs/specification/configuration.md delete mode 100644 docs/specification/configuration.rst create mode 100644 docs/specification/rpc.md delete mode 100644 docs/specification/rpc.rst diff --git a/docs/ecosystem.md b/docs/ecosystem.md index 9fbc56f8e..6b7f833a8 100644 --- a/docs/ecosystem.md +++ b/docs/ecosystem.md @@ -12,7 +12,7 @@ to include your project. ## Other Tools -See [deploy testnets](./deploy-testnets.html) for information about all +See [deploy testnets](./deploy-testnets) for information about all the tools built by Tendermint. We have Kubernetes, Ansible, and Terraform integrations. diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 000000000..ff101715b --- /dev/null +++ b/docs/install.md @@ -0,0 +1,76 @@ +# Install Tendermint + +The fastest and easiest way to install the `tendermint` binary +is to run [this script](https://github.com/tendermint/tendermint/blob/develop/scripts/install/install_tendermint_ubuntu.sh) on +a fresh Ubuntu instance, +or [this script](https://github.com/tendermint/tendermint/blob/develop/scripts/install/install_tendermint_bsd.sh) +on a fresh FreeBSD instance. Read the comments / instructions carefully (i.e., reset your terminal after running the script, +make sure your okay with the network connections being made). + +## From Binary + +To download pre-built binaries, see the [releases page](https://github.com/tendermint/tendermint/releases). + +## From Source + +You'll need `go` [installed](https://golang.org/doc/install) and the required +[environment variables set](https://github.com/tendermint/tendermint/wiki/Setting-GOPATH) + +### Get Source Code + +``` +mkdir -p $GOPATH/src/github.com/tendermint +cd $GOPATH/src/github.com/tendermint +git clone https://github.com/tendermint/tendermint.git +cd tendermint +``` + +### Get Tools & Dependencies + +``` +make get_tools +make get_vendor_deps +``` + +### Compile + +``` +make install +``` + +to put the binary in `$GOPATH/bin` or use: + +``` +make build +``` + +to put the binary in `./build`. + +The latest `tendermint version` is now installed. + +## Reinstall + +If you already have Tendermint installed, and you make updates, simply + +``` +cd $GOPATH/src/github.com/tendermint/tendermint +make install +``` + +To upgrade, run + +``` +cd $GOPATH/src/github.com/tendermint/tendermint +git pull origin master +make get_vendor_deps +make install +``` + +## Run + +To start a one-node blockchain with a simple in-process application: + +``` +tendermint init +tendermint node --proxy_app=kvstore +``` diff --git a/docs/install.rst b/docs/install.rst deleted file mode 100644 index 7ae87eae7..000000000 --- a/docs/install.rst +++ /dev/null @@ -1,99 +0,0 @@ -Install Tendermint -================== - -The fastest and easiest way to install the ``tendermint`` binary -is to run `this script `__ on -a fresh Ubuntu instance, -or `this script `__ -on a fresh FreeBSD instance. Read the comments / instructions carefully (i.e., reset your terminal after running the script, -make sure your okay with the network connections being made). - -From Binary ------------ - -To download pre-built binaries, see the `releases page `__. - -From Source ------------ - -You'll need ``go`` `installed `__ and the required -`environment variables set `__ - -Get Source Code -^^^^^^^^^^^^^^^ - -:: - - mkdir -p $GOPATH/src/github.com/tendermint - cd $GOPATH/src/github.com/tendermint - git clone https://github.com/tendermint/tendermint.git - cd tendermint - -Get Tools & Dependencies -^^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - make get_tools - make get_vendor_deps - -Compile -^^^^^^^ - -:: - - make install - -to put the binary in ``$GOPATH/bin`` or use: - -:: - - make build - -to put the binary in ``./build``. - -The latest ``tendermint version`` is now installed. - -Reinstall ---------- - -If you already have Tendermint installed, and you make updates, simply - -:: - - cd $GOPATH/src/github.com/tendermint/tendermint - make install - -To upgrade, there are a few options: - -- set a new ``$GOPATH`` and run - ``go get github.com/tendermint/tendermint/cmd/tendermint``. This - makes a fresh copy of everything for the new version. -- run ``go get -u github.com/tendermint/tendermint/cmd/tendermint``, - where the ``-u`` fetches the latest updates for the repository and - its dependencies -- fetch and checkout the latest master branch in - ``$GOPATH/src/github.com/tendermint/tendermint``, and then run - ``make get_vendor_deps && make install`` as above. - -Note the first two options should usually work, but may fail. If they -do, use ``dep``, as above: - -:: - - cd $GOPATH/src/github.com/tendermint/tendermint - make get_vendor_deps - make install - -Since the third option just uses ``dep`` right away, it should always -work. - -Run -^^^ - -To start a one-node blockchain with a simple in-process application: - -:: - - tendermint init - tendermint node --proxy_app=kvstore diff --git a/docs/specification/configuration.md b/docs/specification/configuration.md new file mode 100644 index 000000000..d39aa3cb2 --- /dev/null +++ b/docs/specification/configuration.md @@ -0,0 +1,189 @@ +# Configuration + +Tendermint Core can be configured via a TOML file in +`$TMHOME/config/config.toml`. Some of these parameters can be overridden by +command-line flags. For most users, the options in the `##### main +base configuration options #####` are intended to be modified while +config options further below are intended for advance power users. + +## Options + +The default configuration file create by `tendermint init` has all +the parameters set with their default values. It will look something +like the file below, however, double check by inspecting the +`config.toml` created with your version of `tendermint` installed: + +``` +# This is a TOML config file. +# For more information, see https://github.com/toml-lang/toml + +##### main base config options ##### + +# TCP or UNIX socket address of the ABCI application, +# or the name of an ABCI application compiled in with the Tendermint binary +proxy_app = "tcp://127.0.0.1:26658" + +# A custom human readable name for this node +moniker = "anonymous" + +# If this node is many blocks behind the tip of the chain, FastSync +# allows them to catchup quickly by downloading blocks in parallel +# and verifying their commits +fast_sync = true + +# Database backend: leveldb | memdb +db_backend = "leveldb" + +# Database directory +db_path = "data" + +# Output level for logging +log_level = "state:info,*:error" + +##### additional base config options ##### + +# The ID of the chain to join (should be signed with every transaction and vote) +chain_id = "" + +# Path to the JSON file containing the initial validator set and other meta data +genesis_file = "genesis.json" + +# Path to the JSON file containing the private key to use as a validator in the consensus protocol +priv_validator_file = "priv_validator.json" + +# Mechanism to connect to the ABCI application: socket | grpc +abci = "socket" + +# TCP or UNIX socket address for the profiling server to listen on +prof_laddr = "" + +# If true, query the ABCI app on connecting to a new peer +# so the app can decide if we should keep the connection or not +filter_peers = false + +##### advanced configuration options ##### + +##### rpc server configuration options ##### +[rpc] + +# TCP or UNIX socket address for the RPC server to listen on +laddr = "tcp://0.0.0.0:26657" + +# TCP or UNIX socket address for the gRPC server to listen on +# NOTE: This server only supports /broadcast_tx_commit +grpc_laddr = "" + +# Activate unsafe RPC commands like /dial_seeds and /unsafe_flush_mempool +unsafe = false + +##### peer to peer configuration options ##### +[p2p] + +# Address to listen for incoming connections +laddr = "tcp://0.0.0.0:26656" + +# Comma separated list of seed nodes to connect to +seeds = "" + +# Comma separated list of nodes to keep persistent connections to +# Do not add private peers to this list if you don't want them advertised +persistent_peers = "" + +# Path to address book +addr_book_file = "addrbook.json" + +# Set true for strict address routability rules +addr_book_strict = true + +# Time to wait before flushing messages out on the connection, in ms +flush_throttle_timeout = 100 + +# Maximum number of peers to connect to +max_num_peers = 50 + +# Maximum size of a message packet payload, in bytes +max_msg_packet_payload_size = 1024 + +# Rate at which packets can be sent, in bytes/second +send_rate = 512000 + +# Rate at which packets can be received, in bytes/second +recv_rate = 512000 + +# Set true to enable the peer-exchange reactor +pex = true + +# Seed mode, in which node constantly crawls the network and looks for +# peers. If another node asks it for addresses, it responds and disconnects. +# +# Does not work if the peer-exchange reactor is disabled. +seed_mode = false + +# Comma separated list of peer IDs to keep private (will not be gossiped to other peers) +private_peer_ids = "" + +##### mempool configuration options ##### +[mempool] + +recheck = true +recheck_empty = true +broadcast = true +wal_dir = "data/mempool.wal" + +# size of the mempool +size = 100000 + +# size of the cache (used to filter transactions we saw earlier) +cache_size = 100000 + +##### consensus configuration options ##### +[consensus] + +wal_file = "data/cs.wal/wal" + +# All timeouts are in milliseconds +timeout_propose = 3000 +timeout_propose_delta = 500 +timeout_prevote = 1000 +timeout_prevote_delta = 500 +timeout_precommit = 1000 +timeout_precommit_delta = 500 +timeout_commit = 1000 + +# Make progress as soon as we have all the precommits (as if TimeoutCommit = 0) +skip_timeout_commit = false + +# BlockSize +max_block_size_txs = 10000 +max_block_size_bytes = 1 + +# EmptyBlocks mode and possible interval between empty blocks in seconds +create_empty_blocks = true +create_empty_blocks_interval = 0 + +# Reactor sleep duration parameters are in milliseconds +peer_gossip_sleep_duration = 100 +peer_query_maj23_sleep_duration = 2000 + +##### transactions indexer configuration options ##### +[tx_index] + +# What indexer to use for transactions +# +# Options: +# 1) "null" (default) +# 2) "kv" - the simplest possible indexer, backed by key-value storage (defaults to levelDB; see DBBackend). +indexer = "{{ .TxIndex.Indexer }}" + +# Comma-separated list of tags to index (by default the only tag is tx hash) +# +# It's recommended to index only a subset of tags due to possible memory +# bloat. This is, of course, depends on the indexer's DB and the volume of +# transactions. +index_tags = "{{ .TxIndex.IndexTags }}" + +# When set to true, tells indexer to index all tags. Note this may be not +# desirable (see the comment above). IndexTags has a precedence over +# IndexAllTags (i.e. when given both, IndexTags will be indexed). +index_all_tags = {{ .TxIndex.IndexAllTags }} +``` diff --git a/docs/specification/configuration.rst b/docs/specification/configuration.rst deleted file mode 100644 index d7a030039..000000000 --- a/docs/specification/configuration.rst +++ /dev/null @@ -1,191 +0,0 @@ -Configuration -============= - -Tendermint Core can be configured via a TOML file in -``$TMHOME/config/config.toml``. Some of these parameters can be overridden by -command-line flags. For most users, the options in the ``##### main -base configuration options #####`` are intended to be modified while -config options further below are intended for advance power users. - -Config options -~~~~~~~~~~~~~~ - -The default configuration file create by ``tendermint init`` has all -the parameters set with their default values. It will look something -like the file below, however, double check by inspecting the -``config.toml`` created with your version of ``tendermint`` installed: - -:: - - # This is a TOML config file. - # For more information, see https://github.com/toml-lang/toml - - ##### main base config options ##### - - # TCP or UNIX socket address of the ABCI application, - # or the name of an ABCI application compiled in with the Tendermint binary - proxy_app = "tcp://127.0.0.1:26658" - - # A custom human readable name for this node - moniker = "anonymous" - - # If this node is many blocks behind the tip of the chain, FastSync - # allows them to catchup quickly by downloading blocks in parallel - # and verifying their commits - fast_sync = true - - # Database backend: leveldb | memdb - db_backend = "leveldb" - - # Database directory - db_path = "data" - - # Output level for logging - log_level = "state:info,*:error" - - ##### additional base config options ##### - - # The ID of the chain to join (should be signed with every transaction and vote) - chain_id = "" - - # Path to the JSON file containing the initial validator set and other meta data - genesis_file = "genesis.json" - - # Path to the JSON file containing the private key to use as a validator in the consensus protocol - priv_validator_file = "priv_validator.json" - - # Mechanism to connect to the ABCI application: socket | grpc - abci = "socket" - - # TCP or UNIX socket address for the profiling server to listen on - prof_laddr = "" - - # If true, query the ABCI app on connecting to a new peer - # so the app can decide if we should keep the connection or not - filter_peers = false - - ##### advanced configuration options ##### - - ##### rpc server configuration options ##### - [rpc] - - # TCP or UNIX socket address for the RPC server to listen on - laddr = "tcp://0.0.0.0:26657" - - # TCP or UNIX socket address for the gRPC server to listen on - # NOTE: This server only supports /broadcast_tx_commit - grpc_laddr = "" - - # Activate unsafe RPC commands like /dial_seeds and /unsafe_flush_mempool - unsafe = false - - ##### peer to peer configuration options ##### - [p2p] - - # Address to listen for incoming connections - laddr = "tcp://0.0.0.0:26656" - - # Comma separated list of seed nodes to connect to - seeds = "" - - # Comma separated list of nodes to keep persistent connections to - # Do not add private peers to this list if you don't want them advertised - persistent_peers = "" - - # Path to address book - addr_book_file = "addrbook.json" - - # Set true for strict address routability rules - addr_book_strict = true - - # Time to wait before flushing messages out on the connection, in ms - flush_throttle_timeout = 100 - - # Maximum number of peers to connect to - max_num_peers = 50 - - # Maximum size of a message packet payload, in bytes - max_msg_packet_payload_size = 1024 - - # Rate at which packets can be sent, in bytes/second - send_rate = 512000 - - # Rate at which packets can be received, in bytes/second - recv_rate = 512000 - - # Set true to enable the peer-exchange reactor - pex = true - - # Seed mode, in which node constantly crawls the network and looks for - # peers. If another node asks it for addresses, it responds and disconnects. - # - # Does not work if the peer-exchange reactor is disabled. - seed_mode = false - - # Comma separated list of peer IDs to keep private (will not be gossiped to other peers) - private_peer_ids = "" - - ##### mempool configuration options ##### - [mempool] - - recheck = true - recheck_empty = true - broadcast = true - wal_dir = "data/mempool.wal" - - # size of the mempool - size = 100000 - - # size of the cache (used to filter transactions we saw earlier) - cache_size = 100000 - - ##### consensus configuration options ##### - [consensus] - - wal_file = "data/cs.wal/wal" - - # All timeouts are in milliseconds - timeout_propose = 3000 - timeout_propose_delta = 500 - timeout_prevote = 1000 - timeout_prevote_delta = 500 - timeout_precommit = 1000 - timeout_precommit_delta = 500 - timeout_commit = 1000 - - # Make progress as soon as we have all the precommits (as if TimeoutCommit = 0) - skip_timeout_commit = false - - # BlockSize - max_block_size_txs = 10000 - max_block_size_bytes = 1 - - # EmptyBlocks mode and possible interval between empty blocks in seconds - create_empty_blocks = true - create_empty_blocks_interval = 0 - - # Reactor sleep duration parameters are in milliseconds - peer_gossip_sleep_duration = 100 - peer_query_maj23_sleep_duration = 2000 - - ##### transactions indexer configuration options ##### - [tx_index] - - # What indexer to use for transactions - # - # Options: - # 1) "null" (default) - # 2) "kv" - the simplest possible indexer, backed by key-value storage (defaults to levelDB; see DBBackend). - indexer = "{{ .TxIndex.Indexer }}" - - # Comma-separated list of tags to index (by default the only tag is tx hash) - # - # It's recommended to index only a subset of tags due to possible memory - # bloat. This is, of course, depends on the indexer's DB and the volume of - # transactions. - index_tags = "{{ .TxIndex.IndexTags }}" - - # When set to true, tells indexer to index all tags. Note this may be not - # desirable (see the comment above). IndexTags has a precedence over - # IndexAllTags (i.e. when given both, IndexTags will be indexed). - index_all_tags = {{ .TxIndex.IndexAllTags }} diff --git a/docs/specification/rpc.md b/docs/specification/rpc.md new file mode 100644 index 000000000..2f3a72c74 --- /dev/null +++ b/docs/specification/rpc.md @@ -0,0 +1,3 @@ +# RPC + +The RPC documentation is hosted [here](https://tendermint.github.io/slate) and is generated by the CI from our [Slate repo](https://github.com/tendermint/slate). To update the documentation, edit the relevant `godoc` comments in the [rpc/core directory](https://github.com/tendermint/tendermint/tree/develop/rpc/core). diff --git a/docs/specification/rpc.rst b/docs/specification/rpc.rst deleted file mode 100644 index 1dd1165b9..000000000 --- a/docs/specification/rpc.rst +++ /dev/null @@ -1,4 +0,0 @@ -RPC -=== - -The RPC documentation is hosted `here `__ and is generated by the CI from our `Slate repo `__. To update the documentation, edit the relevant ``godoc`` comments in the `rpc/core directory `__. diff --git a/docs/terraform-and-ansible.md b/docs/terraform-and-ansible.md index 13fbeec89..55c38cef7 100644 --- a/docs/terraform-and-ansible.md +++ b/docs/terraform-and-ansible.md @@ -34,13 +34,16 @@ These will be used by both `terraform` and `ansible`. This step will create four Digital Ocean droplets. First, go to the correct directory: - cd $GOPATH/src/github.com/tendermint/tendermint/networks/remote/terraform +``` +cd $GOPATH/src/github.com/tendermint/tendermint/networks/remote/terraform +``` then: - terraform init - terraform apply -var DO_API_TOKEN="$DO_API_TOKEN" -var SSH_KEY_FILE="$SSH_KEY_FILE" - +``` +terraform init +terraform apply -var DO_API_TOKEN="$DO_API_TOKEN" -var SSH_KEY_FILE="$SSH_KEY_FILE" +``` and you will get a list of IP addresses that belong to your droplets. With the droplets created and running, let's setup Ansible. @@ -66,14 +69,18 @@ review [manual deployments](./deploy-testnets.md). Here's the command to run: - ansible-playbook -i inventory/digital_ocean.py -l sentrynet config.yml -e BINARY=$GOPATH/src/github.com/tendermint/tendermint/build/tendermint -e CONFIGDIR=$GOPATH/src/github.com/tendermint/tendermint/docs/examples +``` +ansible-playbook -i inventory/digital_ocean.py -l sentrynet config.yml -e BINARY=$GOPATH/src/github.com/tendermint/tendermint/build/tendermint -e CONFIGDIR=$GOPATH/src/github.com/tendermint/tendermint/docs/examples +``` Voila! All your droplets now have the `tendermint` binary and required configuration files to run a testnet. Next, we run the install role: - ansible-playbook -i inventory/digital_ocean.py -l sentrynet install.yml +``` +ansible-playbook -i inventory/digital_ocean.py -l sentrynet install.yml +``` which as you'll see below, executes `tendermint node --proxy_app=kvstore` on all droplets. Although we'll @@ -88,35 +95,43 @@ increasing). Next, open `roles/install/templates/systemd.service.j2` and look for the line `ExecStart` which should look something like: - ExecStart=/usr/bin/tendermint node --proxy_app=kvstore +``` +ExecStart=/usr/bin/tendermint node --proxy_app=kvstore +``` and add the `--p2p.persistent_peers` flag with the relevant information for each node. The resulting file should look something like: - [Unit] - Description={{service}} - Requires=network-online.target - After=network-online.target - - [Service] - Restart=on-failure - User={{service}} - Group={{service}} - PermissionsStartOnly=true - ExecStart=/usr/bin/tendermint node --proxy_app=kvstore --p2p.persistent_peers=167b80242c300bf0ccfb3ced3dec60dc2a81776e@165.227.41.206:26656,3c7a5920811550c04bf7a0b2f1e02ab52317b5e6@165.227.43.146:26656,303a1a4312c30525c99ba66522dd81cca56a361a@159.89.115.32:26656,b686c2a7f4b1b46dca96af3a0f31a6a7beae0be4@159.89.119.125:26656 - ExecReload=/bin/kill -HUP $MAINPID - KillSignal=SIGTERM - - [Install] - WantedBy=multi-user.target +``` +[Unit] +Description={{service}} +Requires=network-online.target +After=network-online.target + +[Service] +Restart=on-failure +User={{service}} +Group={{service}} +PermissionsStartOnly=true +ExecStart=/usr/bin/tendermint node --proxy_app=kvstore --p2p.persistent_peers=167b80242c300bf0ccfb3ced3dec60dc2a81776e@165.227.41.206:26656,3c7a5920811550c04bf7a0b2f1e02ab52317b5e6@165.227.43.146:26656,303a1a4312c30525c99ba66522dd81cca56a361a@159.89.115.32:26656,b686c2a7f4b1b46dca96af3a0f31a6a7beae0be4@159.89.119.125:26656 +ExecReload=/bin/kill -HUP $MAINPID +KillSignal=SIGTERM + +[Install] +WantedBy=multi-user.target +``` Then, stop the nodes: - ansible-playbook -i inventory/digital_ocean.py -l sentrynet stop.yml +``` +ansible-playbook -i inventory/digital_ocean.py -l sentrynet stop.yml +``` Finally, we run the install role again: - ansible-playbook -i inventory/digital_ocean.py -l sentrynet install.yml +``` +ansible-playbook -i inventory/digital_ocean.py -l sentrynet install.yml +``` to re-run `tendermint node` with the new flag, on all droplets. The `latest_block_hash` should now be changing and `latest_block_height` @@ -124,7 +139,9 @@ increasing. Your testnet is now up and running :) Peek at the logs with the status role: - ansible-playbook -i inventory/digital_ocean.py -l sentrynet status.yml +``` +ansible-playbook -i inventory/digital_ocean.py -l sentrynet status.yml +``` ### Logging @@ -134,14 +151,18 @@ service provider. You can set up your nodes to log there automatically. Create an account and get your API key from the notes on [this page](https://app.logz.io/#/dashboard/data-sources/Filebeat), then: - yum install systemd-devel || echo "This will only work on RHEL-based systems." - apt-get install libsystemd-dev || echo "This will only work on Debian-based systems." - - go get github.com/mheese/journalbeat - ansible-playbook -i inventory/digital_ocean.py -l sentrynet logzio.yml -e LOGZIO_TOKEN=ABCDEFGHIJKLMNOPQRSTUVWXYZ012345 +``` +yum install systemd-devel || echo "This will only work on RHEL-based systems." +apt-get install libsystemd-dev || echo "This will only work on Debian-based systems." + +go get github.com/mheese/journalbeat +ansible-playbook -i inventory/digital_ocean.py -l sentrynet logzio.yml -e LOGZIO_TOKEN=ABCDEFGHIJKLMNOPQRSTUVWXYZ012345 +``` ### Cleanup To remove your droplets, run: - terraform destroy -var DO_API_TOKEN="$DO_API_TOKEN" -var SSH_KEY_FILE="$SSH_KEY_FILE" +``` +terraform destroy -var DO_API_TOKEN="$DO_API_TOKEN" -var SSH_KEY_FILE="$SSH_KEY_FILE" +```