This guide walks you through setting up a Shibarium (or Puppynet) validator node using Ansible. Follow each step in order for a successful deployment. For system requirements, see the Validator Node System Requirements.

​
Prerequisites

  • Three machines:
    • Local machine (runs Ansible playbook)
    • Remote Sentry node
    • Remote Validator node
  • Local machine:
    • Ansible installed
    • Python 3.x installed
  • Remote machines:
    • Go must not be installed
    • Your local machine’s SSH public key added for Ansible access
Always set up the Sentry node before the Validator node. Follow the exact sequence to avoid issues.

​
Overview: Sequence of Actions

1

Prepare all three machines

Ensure your local, sentry, and validator machines are ready and meet all prerequisites.
2

Set up the Sentry node with Ansible

Clone the node-ansible repo and configure inventory.
3

Set up the Validator node with Ansible

Run the playbook for the validator node after the sentry is ready.
4

Configure the Sentry node

Edit Heimdall and Bor configs as required.
5

Start the Sentry node

Start Heimdall and Bor services on the sentry node.
6

Configure the Validator node

Edit Heimdall and Bor configs as required.
7

Set the owner and signer keys

Generate and configure keys for validator operation.
8

Start the Validator node

Start Heimdall and Bor services on the validator node.
9

Check node health with the community

Verify your node is healthy and connected.

​
Set Up the Sentry Node

  1. Clone the node-ansible repository: 
    git clone https://github.com/shibaone/node-ansible
cd node-ansible
  2. Add IPs to inventory.yml: 
    # add your instance ips here
134.209.100.175 # Example IP for sentry/validator node
  3. Check remote sentry machine is reachable: 
    ansible sentry -m ping
    Output should include "ping": "pong".
  4. Test run of sentry node setup: 
    ansible-playbook playbooks/network.yml --extra-var="bor_version=v1.x.x-bone heimdall_version=v1.x.x-bone network=shibarium node_type=sentry" --list-hosts
  5. Run the sentry node setup with sudo: 
    ansible-playbook -l sentry playbooks/network.yml --extra-var="bor_version=v1.x.x-bone heimdall_version=v1.x.x-bone network_version=shibarium node_type=sentry/sentry heimdall_network=shibarium" --ask-become-pass
  6. If you need to start over: 
    ansible-playbook -l sentry playbooks/clean.yml

​
Set Up the Validator Node

  1. Check remote validator machine is reachable: 
    ansible validator -m ping
  2. Test run of validator node setup: 
    ansible-playbook playbooks/network.yml --extra-var="bor_version=v1.x.x-bone heimdall_version=v1.x.x-bone network=shibarium node_type=sentry" --list-hosts
  3. Run the validator node setup with sudo: 
    ansible-playbook -l validator playbooks/network.yml --extra-var="bor_version=v1.x.x-bone heimdall_version=v1.0.3-bone network_version=shibarium node_type=sentry/validator heimdall_network=shibarium" --ask-become-pass
  4. If you need to start over: 
    ansible-playbook -l validator playbooks/clean.yml

​
Configure the Sentry Node

  • Edit Heimdall config: 
    vi /var/lib/heimdall/config/config.toml
    • moniker = "my-full-node"
    • pex = true
    • private_peer_ids = node ID of validator Heimdall
    • seeds (for Shibarium only): node ID, IP, port
  • Check sync status: 
    curl localhost:26657https://shib-io.openstatus.dev/
    • catching_up: true means syncing, false means fully synced
  • Start Bor service: 
    sudo service bor start
journalctl -u bor.service -f

​
Configure the Validator Node

  • Edit Heimdall config: 
    vi /var/lib/heimdall/config/config.toml
    • moniker = "my-validator-node"
    • pex = false
    • Comment out private_peer_ids
    • Add persistent_peers as sentry node: persistent_peers = "sentryNodeID@sentryIP:26656"
    • prometheus = true
  • Edit heimdall-config.toml: 
    vi /var/lib/heimdall/config/heimdall-config.toml
    • eth_rpc_url = "<your Ethereum mainnet RPC URL>"
  • Edit Bor config: 
    vi /var/lib/bor/config.toml
    • trusted-nodes = ["enode://sentryEnodeID@sentryIP:30303"]

​
Set the Owner and Signer Key

On the validator machine only:
heimdallcli generate-validatorkey ETHEREUM_PRIVATE_KEY
mv ./priv_validator_key.json /var/lib/heimdall/config/
On the validator machine only:
heimdallcli generate-keystore ETHEREUM_PRIVATE_KEY
mv ./UTC-<time>-<address> /var/lib/bor/data/keystore/
Set up a password when prompted, and ensure the keystore parameter in Bor config matches the directory.
Create a password.txt file with the keystore password:
vi /var/lib/bor/password.txt
Ensure the password parameter in Bor config matches this file.
In /var/lib/bor/config.toml, add your Ethereum address to unlock and set allow-insecure-unlock = true:
[accounts]
allow-insecure-unlock = true
password = "/var/lib/bor/password.txt"
unlock = ["0xYourEthereumAddress"]

​
Start the Validator Node

  • Start Heimdall service: 
    sudo service heimdalld start
journalctl -u heimdalld.service -f
curl localhost:26657https://shib-io.openstatus.dev/
    Wait for catching_up: false before starting Bor.
  • Start Bor service: 
    sudo service bor start
journalctl -u bor.service -f
Keep at least 0.5 ETH in your signer address to avoid being unable to submit checkpoint transactions.