Skip to content

Commit f2f0bc1

Browse files
nadimkobeissinadimkobeissi
committed
Example rewrite: Operating a full node how-to
This is an example rewrite of the how-tos for operating a full node, with the intent of being an example of how a rewrite of a section from the wiki into the new docs can look like. An accompanying video demo is available in the Slack: https://0xpolygon.slack.com/archives/C061PHD9UBD/p1700834617950929https://0xpolygon.slack.com/archives/C061PHD9UBD/p1700834617950929
1 parent 6bd1ec5 commit f2f0bc1

File tree

8 files changed

+369
-845
lines changed

8 files changed

+369
-845
lines changed

‎docs/_site_essentials/stylesheets/extra.css‎

Lines changed: 58 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,84 @@
11
[data-md-color-scheme="slate"] {
2-
--md-footer-bg-color: black;
3-
.md-footer, .md-footer__inner, .md-footer-meta {
4-
background-color: black;
5-
}
2+
--md-footer-bg-color: black;
3+
4+
.md-footer,
5+
.md-footer__inner,
6+
.md-footer-meta {
7+
background-color: black;
8+
}
69
}
710

811
[data-md-color-scheme="default"] {
9-
--md-footer-bg-color: white;
10-
--md-footer-fg-color: charcoal;
11-
--md-default-bg-color: white;
12-
--md-footer-fg-color--light: charcoal;
13-
--md-footer-fg-color--lighter: charcoal;
14-
.md-footer, .md-footer__inner, .md-footer-meta {
15-
background-color: white;
16-
}
12+
--md-footer-bg-color: white;
13+
--md-footer-fg-color: charcoal;
14+
--md-default-bg-color: white;
15+
--md-footer-fg-color--light: charcoal;
16+
--md-footer-fg-color--lighter: charcoal;
17+
18+
.md-footer,
19+
.md-footer__inner,
20+
.md-footer-meta {
21+
background-color: white;
22+
}
1723
}
1824

1925
img.figure {
20-
border: 5px solid #ae6fdb !important;
21-
box-shadow: 0 0 10px rgba(0, 0, 0, 0.3);
22-
margin: 0 auto;
23-
max-width: 80%;
24-
display: block;
26+
border: 5px solid #ae6fdb !important;
27+
box-shadow: 0 0 10px rgba(0, 0, 0, 0.3);
28+
margin: 0 auto;
29+
max-width: 80%;
30+
display: block;
2531
}
2632

2733
div.flex-figure {
28-
display: flex;
29-
34+
display: flex;
3035
}
3136

3237
div.flex-figure div.flex-figure-left {
33-
flex-grow: 2;
38+
flex-grow: 2;
3439
}
3540

3641
div.flex-figure div.flex-figure-right {
37-
flex-grow: 1;
38-
flex-shrink: 1.5;
42+
flex-grow: 1;
43+
flex-shrink: 1.5;
44+
}
45+
46+
div.info-box {
47+
border: 5px solid #ae6fdb !important;
48+
box-shadow: 0 0 10px rgba(0, 0, 0, 0.3);
49+
margin: 0 auto;
50+
max-width: 100%;
51+
display: block;
52+
margin-bottom: 20px;
53+
border-radius: 10px;
54+
background-color: #F9F9F9;
3955
}
4056

57+
div.info-box h3 {
58+
margin-top: 0;
59+
margin-bottom: 0;
60+
font-size: 1.1em;
61+
font-weight: bold;
62+
background-color: #ae6fdb;
63+
color: #FFF;
64+
padding: 2px 10px;
65+
border-radius: 2px 2px 0 0;
66+
}
67+
68+
div.info-box p {
69+
margin-top: 0;
70+
margin-bottom: 0;
71+
padding: 8px 10px;
72+
font-size: 0.8em;
73+
line-height: 1.3em;
74+
}
4175

4276
/*
4377
.md-footer, .md-footer__inner, .md-footer-meta {
44-
background-color: black;
78+
background-color: black;
4579
}
4680
*/
4781

4882
.md-footer__inner {
49-
display: none !important;
83+
display: none !important;
5084
}

‎docs/_site_essentials/stylesheets/section-nav.css‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
1-
div.section-nav {
2-
}
1+
div.section-nav {}
32

43
div.section-nav .section-nav-item {
54
border-radius: 20px;

‎docs/pos/howto/operating/full-node/ansible.md‎

Lines changed: 65 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -1,131 +1,97 @@
1-
An [Ansible playbook](https://docs.ansible.com/ansible/latest/user_guide/playbooks_intro.html) is used to
2-
configure and manage a full node.
3-
4-
## Prerequisites
5-
6-
- Install Ansible on your local machine with Python3.x. The setup will not work if you have Python2.x.
7-
- To install Ansible with Python 3.x, you can use pip. If you do not have pip on your machine,
8-
follow the steps outlined [here](https://pip.pypa.io/en/stable/). Run `pip3 install ansible` to install
9-
Ansible.
10-
- Check the [Polygon PoS Ansible repository](https://github.com/maticnetwork/node-ansible#requirements) for
11-
requirements.
12-
- You will also need to ensure that Go is **not installed** in your environment. You will run into issues if you attempt to set up your full node through Ansible with Go installed as Ansible requires specific packages of Go to be installed.
13-
- You will also need to make sure that your VM / Machine does not have any previous setups for Polygon Validator or Heimdall or Bor. You will need to delete them as your setup will run into issues.
14-
15-
:::info Heimdall source enhancements
16-
17-
The latest Heimdall version, **[v1.0.3](https://github.com/maticnetwork/heimdall/releases/tag/v1.0.3)**, contains a few enhancements.
18-
The delay time between the contract events of different validators **has been increased** to ensure that the mempool doesn't get filled
19-
quickly in case of a burst of events that could hamper the chain's progress.
20-
21-
Additionally, the data size **has been restricted in state sync txs to 30Kb (when represented in bytes) and 60Kb (when defined as string)**.
22-
For example:
23-
24-
```bash
25-
Data - "abcd1234"
26-
Length in string format - 8
27-
Hex Byte representation - [171 205 18 52]
28-
Length in byte format - 4
29-
```
30-
:::
31-
32-
## Full node setup
33-
34-
- Ensure you have access to the remote machine or VM on which the full node is being set up.
35-
> Refer to [https://github.com/maticnetwork/node-ansible#setup](https://github.com/maticnetwork/node-ansible#setup) for more details.
36-
- Clone the [https://github.com/maticnetwork/node-ansible](https://github.com/maticnetwork/node-ansible) repository.
37-
- Navigate into the node-ansible folder: `cd node-ansible`
38-
- Edit the `inventory.yml` file and insert your IP(s) in the `sentry->hosts` section.
39-
> Refer to [https://github.com/maticnetwork/node-ansible#inventory](https://github.com/maticnetwork/node-ansible#inventory) for more details.
40-
- Check if the remote machine is reachable by running: `ansible sentry -m ping`
41-
- To test if the correct machine is configured, run the following command:
1+
## Overview of Ansible Playbook Utilization
422

43-
```bash
44-
# Mainnet:
45-
ansible-playbook playbooks/network.yml --extra-var="bor_version=v1.0.0 heimdall_version=v1.0.3 network=mainnet node_type=sentry" --list-hosts
3+
To configure and effectively manage a Polygon full node, we employ an [Ansible playbook](https://docs.ansible.com/ansible/latest/user_guide/playbooks_intro.html). This tool streamlines the process, ensuring a consistent and error-free setup.
4+
5+
## Prerequisites for Ansible Setup
466

47-
# Testnet:
48-
ansible-playbook playbooks/network.yml --extra-var="bor_version=v1.1.0 heimdall_version=v1.0.3 network=mumbai node_type=sentry" --list-hosts
7+
- **Ansible with Python 3.x**: Your local machine must have Ansible installed with Python version 3.x. Note that Python 2.x is incompatible with this setup. Use the following command to install Ansible using pip (Python's package installer). If pip is not installed, refer to [pip installation guidelines](https://pip.pypa.io/en/stable/):
8+
9+
```bash
10+
pip3 install ansible
4911
```
5012

51-
<img src="/img/pos/full-node-mumbai.png")} />
13+
- **Reviewing Requirements**: Before proceeding, check the specific requirements listed in the [Polygon PoS Ansible repository](https://github.com/maticnetwork/node-ansible#requirements).
5214

53-
- Next, set up the full node with this command:
15+
- **Environment Setup**: Ensure that Go is not installed on your environment. Ansible requires specific Go packages, and existing installations could lead to conflicts. Additionally, any pre-existing setups of Polygon Validator, Heimdall, or Bor on your VM/machine must be removed to avoid setup conflicts.
5416

55-
```bash
56-
# Mainnet:
57-
ansible-playbook playbooks/network.yml --extra-var="bor_version=v1.1.0 heimdall_version=v1.0.3 network=mainnet node_type=sentry"
17+
## Setting Up the Full Node
5818

59-
# Testnet:
60-
ansible-playbook playbooks/network.yml --extra-var="bor_version=v1.0.0 heimdall_version=v1.0.3 network=mumbai node_type=sentry"
61-
```
19+
- **Remote Machine Access**: Confirm access to the VM or machine where the full node will be set up. Detailed setup instructions are available at the [node-ansible setup guide](https://github.com/maticnetwork/node-ansible#setup).
6220

63-
- In case you run into any issues, delete and clean the whole setup using:
64-
```
65-
ansible-playbook playbooks/clean.yml
21+
- **Repository Cloning**: Clone the [node-ansible repository](https://github.com/maticnetwork/node-ansible) and navigate to the cloned directory:
22+
23+
```bash
24+
git clone https://github.com/maticnetwork/node-ansible
25+
cd node-ansible
6626
```
6727

68-
- Once you initiate the Ansible playbook, log in to the remote machine.
28+
- **Configuration File Editing**: In the `node-ansible` directory, edit the `inventory.yml` file to include your machine's IP address under the `sentry->hosts` section. Detailed instructions can be found [here](https://github.com/maticnetwork/node-ansible#inventory).
6929

70-
- Please **ensure that the value of seeds and bootnodes mentioned below is the same value as mentioned in Heimdall and Bor `config.toml` files**. If not, change the values accordingly.
30+
- **Connectivity Check**: Verify the remote machine's connectivity:
7131

72-
- Heimdall seed nodes:
32+
```bash
33+
ansible sentry -m ping
34+
```
7335

74-
```bash
75-
moniker=<enter unique identifier>
36+
- **Testing Machine Configuration**: Run the following commands to ensure you have configured the correct machine:
7637

77-
# Mainnet:
78-
seeds="1500161dd491b67fb1ac81868952be49e2509c9f@52.78.36.216:26656,dd4a3f1750af5765266231b9d8ac764599921736@3.36.224.80:26656,8ea4f592ad6cc38d7532aff418d1fb97052463af@34.240.245.39:26656,e772e1fb8c3492a9570a377a5eafdb1dc53cd778@54.194.245.5:26656,6726b826df45ac8e9afb4bdb2469c7771bd797f1@52.209.21.164:26656"
38+
```bash
39+
# For Mainnet:
40+
ansible-playbook playbooks/network.yml --extra-vars="bor_version=v1.0.0 heimdall_version=v1.0.3 network=mainnet node_type=sentry" --list-hosts
7941

80-
# Testnet:
81-
seeds="9df7ae4bf9b996c0e3436ed4cd3050dbc5742a28@43.200.206.40:26656,d9275750bc877b0276c374307f0fd7eae1d71e35@54.216.248.9:26656,1a3258eb2b69b235d4749cf9266a94567d6c0199@52.214.83.78:26656"
82-
```
83-
- Bootnodes:
42+
# For Testnet:
43+
ansible-playbook playbooks/network.yml --extra-vars="bor_version=v1.1.0 heimdall_version=v1.0.3 network=mumbai node_type=sentry" --list-hosts
44+
```
8445

85-
```bash
86-
# Mainnet:
87-
bootnode ["enode://b8f1cc9c5d4403703fbf377116469667d2b1823c0daf16b7250aa576bacf399e42c3930ccfcb02c5df6879565a2b8931335565f0e8d3f8e72385ecf4a4bf160a@3.36.224.80:30303", "enode://8729e0c825f3d9cad382555f3e46dcff21af323e89025a0e6312df541f4a9e73abfa562d64906f5e59c51fe6f0501b3e61b07979606c56329c020ed739910759@54.194.245.5:30303"]
46+
- **Full Node Setup**: Execute these commands to set up the full node:
8847

89-
# Testnet:
90-
bootnodes ["enode://bdcd4786a616a853b8a041f53496d853c68d99d54ff305615cd91c03cd56895e0a7f6e9f35dbf89131044e2114a9a782b792b5661e3aff07faf125a98606a071@43.200.206.40:30303", "enode://209aaf7ed549cf4a5700fd833da25413f80a1248bd3aa7fe2a87203e3f7b236dd729579e5c8df61c97bf508281bae4969d6de76a7393bcbd04a0af70270333b3@54.216.248.9:30303"]
91-
```
48+
```bash
49+
# For Mainnet:
50+
ansible-playbook playbooks/network.yml --extra-vars="bor_version=v1.1.0 heimdall_version=v1.0.3 network=mainnet node_type=sentry"
9251

93-
- To check if Heimdall is synced
94-
- On the remote machine/VM, run `curl localhost:26657/status`
95-
- In the output, `catching_up` value should be `false`
52+
# For Testnet:
53+
ansible-playbook playbooks/network.yml --extra-vars="bor_version=v1.0.0 heimdall_version=v1.0.3 network=mumbai node_type=sentry"
54+
```
9655

97-
- Once Heimdall is synced, run
98-
- `sudo service bor start`
56+
- **Troubleshooting**: In case of issues, use the following command to clean and reset the setup:
9957

100-
You have successfully set up a full node with Ansible.
58+
```bash
59+
ansible-playbook playbooks/clean.yml
60+
```
10161

102-
:::note
62+
- **Post-Setup Verification**: Log in to the remote machine and verify that the seeds and bootnodes in Heimdall and Bor `config.toml` files match the provided values. Update them if necessary.
10363

104-
If Bor presents an error of permission to data, run this command to make the Bor user the owner of the Bor files:
64+
- **Syncing Heimdall**: To check if Heimdall is fully synced:
10565

106-
```bash
107-
sudo chown bor /var/lib/bor
108-
```
66+
```bash
67+
curl localhost:26657/status
68+
# The 'catching_up' value should be 'false'
69+
```
10970

110-
:::
111-
## Logs
71+
- **Starting Bor**: Once Heimdall is synced, initiate Bor:
11272

113-
Logs can be managed by the `journalctl` linux tool. Here is a tutorial for advanced usage: [How To Use Journalctl to View and Manipulate Systemd Logs](https://www.digitalocean.com/community/tutorials/how-to-use-journalctl-to-view-and-manipulate-systemd-logs).
73+
```bash
74+
sudo service bor start
75+
```
76+
77+
## Managing Logs and Permissions
11478

115-
**Check Heimdall node logs**
79+
- **Logs**: Use `journalctl` for log management. For advanced usage, refer to [this tutorial](https://www.digitalocean.com/community/tutorials/how-to-use-journalctl-to-view-and-manipulate-systemd-logs).
11680

117-
```bash
118-
journalctl -u heimdalld.service -f
119-
```
81+
- **Heimdall Node Logs**: `journalctl -u heimdalld.service -f`
82+
- **Bor Service Logs**: `journalctl -u bor.service -f`
12083

121-
**Check Bor Rest-server logs**
84+
- **Permission Issues**: If Bor encounters permission issues, run:
85+
86+
```bash
87+
sudo chown bor /var/lib/bor
88+
```
12289

123-
```bash
124-
journalctl -u bor.service -f
125-
```
90+
## Network Security and Port Configuration
12691

127-
## Ports and Firewall Setup
92+
- **Firewall Setup**: Open ports 22, 26656, and 30303 to all (0.
12893

129-
Open ports 22, 26656 and 30303 to world (0.0.0.0/0) on sentry node firewall.
94+
0.0.0/0) on the sentry node firewall.
95+
- **Enhanced Security**: Consider using a VPN to restrict access to port 22 as per your security needs.
13096

131-
You can use VPN to restrict access for port 22 as per your requirement and security guidelines.
97+
Congratulations! You have successfully configured and started a Polygon full node using Ansible. Remember to routinely check your setup for optimal performance and security compliance.

0 commit comments

Comments
 (0)