mirrors/tendermint
1
0
Fork 0
mirror of https://github.com/tendermint/tendermint.git synced 2026-07-31 04:22:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add roadmap to repo (#7107)

Browse Source
This commit is contained in:
Callum Waters
2021-10-15 10:35:36 +02:00
committed by GitHub
parent b95c261981
commit c3dc7d20df
11 changed files with 119 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/tools/README.md
+8
View File
@@ -27,3 +27,11 @@ testing Tendermint networks.
This repository contains various different configurations of test networks for,
and relating to, Tendermint.
Use [Docker Compose](./docker-compose.md) to spin up Tendermint testnets on your
local machine.
Use [Terraform and Ansible](./terraform-and-ansible.md) to deploy Tendermint
testnets to the cloud.
See the `tendermint testnet --help` command for more help initializing testnets.
docs/tools/docker-compose.md
+184
View File
@@ -0,0 +1,184 @@
---
order: 2
---
# Docker Compose
With Docker Compose, you can spin up local testnets with a single command.
## Requirements
1. [Install tendermint](../introduction/install.md)
2. [Install docker](https://docs.docker.com/engine/installation/)
3. [Install docker-compose](https://docs.docker.com/compose/install/)
## Build
Build the `tendermint` binary and, optionally, the `tendermint/localnode`
docker image.
Note the binary will be mounted into the container so it can be updated without
rebuilding the image.
```sh
# Build the linux binary in ./build
make build-linux
# (optionally) Build tendermint/localnode image
make build-docker-localnode
```
## Run a testnet
To start a 4 node testnet run:
```sh
make localnet-start
```
The nodes bind their RPC servers to ports 26657, 26660, 26662, and 26664 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 26656-26657, 26659-26660, 26661-26662, and 26663-26664 respectively.
The first node (`node0`) exposes two additional ports: 6060 for profiling using
[`pprof`](https://golang.org/pkg/net/http/pprof), and `9090` - for Prometheus
server (if you don't know how to start one check out ["First steps |
Prometheus"](https://prometheus.io/docs/introduction/first_steps/)).
To update the binary, just rebuild it and restart the nodes:
```sh
make build-linux
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.
To change the number of validators / non-validators change the `localnet-start` Makefile target [here](../../Makefile):
```makefile
localnet-start: localnet-stop
@if ! [ -f build/node0/config/genesis.json ]; then docker run --rm -v $(CURDIR)/build:/tendermint:Z tendermint/localnode testnet --v 5 --n 3 --o . --populate-persistent-peers --starting-ip-address 192.167.10.2 ; fi
docker-compose up
```
The command now will generate config files for 5 validators and 3
non-validators. Along with generating new config files the docker-compose file needs to be edited.
Adding 4 more nodes is required in order to fully utilize the config files that were generated.
```yml
node3: # bump by 1 for every node
container_name: node3 # bump by 1 for every node
image: "tendermint/localnode"
environment:
- ID=3
- LOG=${LOG:-tendermint.log}
ports:
- "26663-26664:26656-26657" # Bump 26663-26664 by one for every node
volumes:
- ./build:/tendermint:Z
networks:
localnet:
ipv4_address: 192.167.10.5 # bump the final digit by 1 for every node
```
Before running it, don't forget to cleanup the old files:
```sh
# Clear the build folder
rm -rf ./build/node*
```
## Configuring ABCI containers
To use your own ABCI applications with 4-node setup edit the [docker-compose.yaml](https://github.com/tendermint/tendermint/blob/master/docker-compose.yml) file and add image to your ABCI application.
```yml
abci0:
container_name: abci0
image: "abci-image"
build:
context: .
dockerfile: abci.Dockerfile
command: <insert command to run your abci application>
networks:
localnet:
ipv4_address: 192.167.10.6
abci1:
container_name: abci1
image: "abci-image"
build:
context: .
dockerfile: abci.Dockerfile
command: <insert command to run your abci application>
networks:
localnet:
ipv4_address: 192.167.10.7
abci2:
container_name: abci2
image: "abci-image"
build:
context: .
dockerfile: abci.Dockerfile
command: <insert command to run your abci application>
networks:
localnet:
ipv4_address: 192.167.10.8
abci3:
container_name: abci3
image: "abci-image"
build:
context: .
dockerfile: abci.Dockerfile
command: <insert command to run your abci application>
networks:
localnet:
ipv4_address: 192.167.10.9
```
Override the [command](https://github.com/tendermint/tendermint/blob/master/networks/local/localnode/Dockerfile#L12) in each node to connect to it's ABCI.
```yml
node0:
container_name: node0
image: "tendermint/localnode"
ports:
- "26656-26657:26656-26657"
environment:
- ID=0
- LOG=$${LOG:-tendermint.log}
volumes:
- ./build:/tendermint:Z
command: node --proxy-app=tcp://abci0:26658
networks:
localnet:
ipv4_address: 192.167.10.2
```
Similarly do for node1, node2 and node3 then [run testnet](https://github.com/tendermint/tendermint/blob/master/docs/networks/docker-compose.md#run-a-testnet)
## 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.
docs/tools/terraform-and-ansible.md
+177
View File
@@ -0,0 +1,177 @@
---
order: 3
---
# Terraform & Ansible
> Note: These commands/files are not being maintained by the tendermint team currently. Please use them carefully.
Automated deployments are done using
[Terraform](https://www.terraform.io/) to create servers on Digital
Ocean then [Ansible](http://www.ansible.com/) to create and manage
testnets on those servers.
## Install
NOTE: see the [integration bash
script](https://github.com/tendermint/tendermint/blob/master/networks/remote/integration.sh)
that can be run on a fresh DO droplet and will automatically spin up a 4
node testnet. The script more or less does everything described below.
- Install [Terraform](https://www.terraform.io/downloads.html) and
[Ansible](http://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html)
on a Linux machine.
- Create a [DigitalOcean API
token](https://cloud.digitalocean.com/settings/api/tokens) with read
and write capability.
- Install the python dopy package (`pip install dopy`)
- Create SSH keys (`ssh-keygen`)
- Set environment variables:
```sh
export DO_API_TOKEN="abcdef01234567890abcdef01234567890"
export SSH_KEY_FILE="$HOME/.ssh/id_rsa.pub"
```
These will be used by both `terraform` and `ansible`.
## Terraform
This step will create four Digital Ocean droplets. First, go to the
correct directory:
```sh
cd $GOPATH/src/github.com/tendermint/tendermint/networks/remote/terraform
```
then:
```sh
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.
## Ansible
The playbooks in [the ansible
directory](https://github.com/tendermint/tendermint/tree/master/networks/remote/ansible)
run ansible roles to configure the sentry node architecture. You must
switch to this directory to run ansible
(`cd $GOPATH/src/github.com/tendermint/tendermint/networks/remote/ansible`).
There are several roles that are self-explanatory:
First, we configure our droplets by specifying the paths for tendermint
(`BINARY`) and the node files (`CONFIGDIR`). The latter expects any
number of directories named `node0, node1, ...` and so on (equal to the
number of droplets created).
To create the node files run:
```sh
tendermint testnet
```
Then, to configure our droplets run:
```sh
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/networks/remote/ansible/mytestnet
```
Voila! All your droplets now have the `tendermint` binary and required
configuration files to run a testnet.
Next, we run the install role:
```sh
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
soon be modifying this role and running it again, this first execution
allows us to get each `node_info.id` that corresponds to each
`node_info.listen_addr`. (This part will be automated in the future). In
your browser (or using `curl`), for every droplet, go to IP:26657/status
and note the two just mentioned `node_info` fields. Notice that blocks
aren't being created (`latest_block_height` should be zero and not
increasing).
Next, open `roles/install/templates/systemd.service.j2` and look for the
line `ExecStart` which should look something like:
```sh
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:
```sh
[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:
```sh
ansible-playbook -i inventory/digital_ocean.py -l sentrynet stop.yml
```
Finally, we run the install role again:
```sh
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`
increasing. Your testnet is now up and running :)
Peek at the logs with the status role:
```sh
ansible-playbook -i inventory/digital_ocean.py -l sentrynet status.yml
```
## Logging
The crudest way is the status role described above. You can also ship
logs to Logz.io, an Elastic stack (Elastic search, Logstash and Kibana)
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:
```sh
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:
```sh
terraform destroy -var DO_API_TOKEN="$DO_API_TOKEN" -var SSH_KEY_FILE="$SSH_KEY_FILE"
```