tokenbridge/deployment/oracle
Przemyslaw Rzad 93347b47a8
Updates after deployment test (#75)
* Force ln to mitigate error when postinstall is repeated

* Update readme

* Using yarn in place of npm run

* Changed env order - home first

* Removed gh-pages UI deploy

* Readme cosmetics

* Removed duplicate bridge overview

* Update readme

* Update repository address

* Update readme

* Changed NPM to Yarn everywhere

* Update readme

* Using tokenbridge monorepo in deployment instead of token-bridge

* Update ui/README.md

Co-Authored-By: Andrew Gross <andogro@gmail.com>

* Revert and/or change as per @akolotov explanation

* Removed checkWorker3 that was used in legacy bridge-rust-v1-native-to-erc

* Update deployment/oracle/README.md

Co-Authored-By: Alexander Kolotov <alexandr.kolotov@gmail.com>

* Apply suggestions from code review

Co-Authored-By: Alexander Kolotov <alexandr.kolotov@gmail.com>

* Update root readme and Update sub-repo readmes to point to root monorepository initialization.

* Removed obsolete GET /stuckTransfers

* Remove stuckTransfers

* Use shell instead of unmaintained docker_service module. Update naming in templates.
2019-05-31 14:54:32 +02:00
..
group_vars Update deployment bridge (#37) 2019-05-10 14:04:20 +02:00
roles Updates after deployment test (#75) 2019-05-31 14:54:32 +02:00
ansible.cfg Update deployment bridge (#37) 2019-05-10 14:04:20 +02:00
hosts.yml.example Update deployment bridge (#37) 2019-05-10 14:04:20 +02:00
README.md Updates after deployment test (#75) 2019-05-31 14:54:32 +02:00
site.yml Update deployment bridge (#37) 2019-05-10 14:04:20 +02:00

Prerequisites

  1. A functional Ubuntu 16.04 server launched using a trusted hosting provider. For more information, see our tutorials on setting up a validator node on AWS or setting up on non-AWS.

    • Record the IP address (required for file setup).
    • Setup ssh access to your node via public+private keys (using passwords is less secure).
    • When creating the node, set a meaningful hostname that can identify you (e.g. validator-0x...).
  2. On your local machine install:

    • Python 2 (v2.6-v2.7)/Python3 (v3.5+)
    • Ansible v2.3+
    • Git

Configuration

  1. Clone this repository and go to the deployment/oracle folder
git clone --recursive https://github.com/poanetwork/tokenbridge
cd tokenbridge/deployment/oracle
  1. Create the file hosts.yml from hosts.yml.example
cp hosts.yml.example hosts.yml

hosts.yml should have the following structure:

<bridge_name>:
    hosts:
        <host_ip>:
            ansible_user: <user>
            VALIDATOR_ADDRESS_PRIVATE_KEY: "<private_key>"
            #syslog_server_port: "<protocol>://<ip>:<port>" # When this parameter is set all bridge logs will be redirected to <ip>:<port> address.
Value Description
<bridge_name> The bridge name which tells Ansible which file to use. This is located in group_vars/<bridge_name>.yml.
<host_ip> Remote server IP address.
ansible_user: <user> User that will ssh into the node. This is typically ubuntu or root.
VALIDATOR_ADDRESS_PRIVATE_KEY: "<private_key>" The private key for the specified validator address.
syslog_server_port: "<protocol>://<ip>:<port>" Optional port specification for bridge logs. This value will be provided by an administrator if required.

hosts.yml can contain multiple hosts and bridge configurations (groups) at once.

  1. Copy the bridge name(s) to the hosts.yml file.
    1. Go to the group_vars folder. cd group_vars
    2. Note the <bridge_name> and add it to the hosts.yml configuration. For example, if a bridge file is named sokol-kovan.yml, you would change the <bridge_name> value in hosts.yml to sokol-kovan.

Administrator Configurations

  1. The group_vars/<bridge_name>.yml file contains the public bridge parameters. This file is prepared by administrators for each bridge. The validator only needs to add the required bridge name in the hosts.yml file to tell Ansible which file to use.

    group_vars/example.yml shows an example configuration for the POA/Sokol - POA/Sokol bridge. Parameter values should match values from the .env file for the Oracle. See Configuration parameters for details.

  2. You can also add the following parameters in the group_vars to change the default behavior of deployment-bridge playbooks:

2.1 compose_service_user - specifies users to be created by playbooks. This user will be used to run Token Bridge Oracle.

2.2 bridge_repo contains address of Token Bridge Oracle repository. The default value is https://github.com/poanetwork/tokenbridge.

2.3 bridge_repo_branch points to the specific branch or commit to use with the bridge_repo. If bridge_repo_branch is not specified, the default (master) branch is used.

2.4 bridge_path set the path where Token Bridge Oracle would be installed. By default it point to the home folder of compose_service_user

2.5 docker_compose_version - specifies a version of docker-compose to be installed.

2.6 ALLOW_HTTP (no by default) can be set to yes to allow bridge insecure connections to the network.

Execution

The playbook can be executed once Ansible is installed and all configuration variables are set.

It will automatically install Docker, docker-compose, Python, Git and it dependencies (such as curl, ca-certificates, apt-transport-https, etc.) to the node. Also this playbooks creates an additional non-sudo docker user to run service as.

ansible-playbook -i hosts.yml site.yml

Useful arguments:

To be used with the ansible-playbook command, for example:

 `ansible-playbook -i hosts.yml site.yml --ask-become-pass`
  • --ask-pass - ask for the password used to connect to the bridge VM.

  • --ask-become-pass - ask for the become password used to execute some commands (such as Docker installation) with root privileges.

  • -i <file> - use specified file as a hosts.yml file.

  • -e "<variable>=<value>" - override default variable.

  • --private-key=<file_name> - if private keyfile is required to connect to the ubuntu instance.

  • --user=<username> - connect as this username

Bridge service commands

The Bridge service is named poabridge. Use the default SysVinit commands to start, stop, restart, and rebuild the service and to check the status of the service.

Commands format:

sudo service poabridge [start|stop|restart|status|rebuild]

Rollback the Last Processed Block in Redis

If the bridge does not handle an event properly (i.e. a transaction stalls due to a low gas price), the Redis DB can be rolled back. You must identify which watcher needs to re-run. For example, if the validator signatures were collected but the transaction with signatures was not sent to the Foreign network, the collected-signatures watcher must look at the block where the corresponding CollectedSignatures event was raised.

Execute the reset-lastBlock.sh script in the bridge root directory. For example, if you've installed your bridge with this deployment script and all the default parameters, use the following set of commands:

$ sudo su poadocker
$ cd ~/bridge
$ docker-compose exec bridge_affirmation bash ./reset-lastBlock.sh <watcher> <block num>
$ exit
$ sudo service poabridge restart

where the could be one of the following:

  • signature-request
  • collected-signatures
  • affirmation-request

Logs

If the syslog_server_port option in the hosts.yml file is not set, all logs will be stored in /var/log/docker/ folder in the set of folders with the bridge_ prefix.

If the syslog_server_port is set, logs will be redirected to the specified server and cannot be accessed on the bridge machine.

syslog_server_port: "<protocol>://<ip>:<port>" # When this parameter is set all bridge logs will be redirected to the <ip>:<port> address.