|
1 | 1 | # TRUF.NETWORK Node Operator Guide |
2 | 2 |
|
3 | | -This guide will walk you through the process of setting up and running a TRUF.NETWORK (TN) node. By following these steps, you'll be able to deploy a node, optionally become a validator, and contribute to the TN v2 mainnet. |
| 3 | +This repository contains configuration files and utilities for running a TRUF.NETWORK (TN) node. |
4 | 4 |
|
5 | | -> **New to server setup or need a quick start?** Check our [Quick Installation Guide](docs/installation-guide.md) with copy-paste commands for a fresh server instance. |
| 5 | +## Documentation |
6 | 6 |
|
7 | | -## Prerequisites |
| 7 | +For detailed instructions on setting up and running a TRUF.NETWORK node, please refer to our official documentation: |
8 | 8 |
|
9 | | -Before you begin, ensure you have the following: |
| 9 | +- [Node Operator Guide](https://trufnetwork.github.io/node-operator-guide) - Comprehensive guide to setting up and running a TN node |
10 | 10 |
|
11 | | -1. **Kwild**: The all-in-one binary for node operation and administration. |
12 | | - - Download from the [latest GitHub release](https://github.com/trufnetwork/node/releases) |
| 11 | +## Repository Contents |
13 | 12 |
|
14 | | -2. **Docker**: Required for running the PostgreSQL image. |
15 | | - - Install from [Docker's official website](https://docs.docker.com/get-docker) |
| 13 | +This repository contains: |
16 | 14 |
|
17 | | -3. **PostgreSQL Client**: Required for state sync and database operations. |
18 | | - - Install with `sudo apt -y install postgresql-16` (Ubuntu/Debian) |
| 15 | +1. **Configuration Files**: Essential network configuration files in the `configs/network/` directory: |
| 16 | + - `v2/genesis.json`: The network's genesis file |
| 17 | + - `v2/network-nodes.csv`: List of available nodes for peer discovery |
19 | 18 |
|
20 | | -## Setup Steps |
| 19 | +2. **Documentation**: Detailed guides in the `docs/` directory: |
| 20 | + - `installation-guide.md`: Quick start guide with copy-paste commands |
| 21 | + - `creating-config.md`: Detailed configuration options for production setups |
21 | 22 |
|
22 | | -### 1. Clone the Repository |
| 23 | +## Getting Help |
23 | 24 |
|
24 | | -First, clone the TRUF.NETWORK node operator repository: |
25 | | - |
26 | | -```bash |
27 | | -git clone https://github.com/trufnetwork/truf-node-operator.git |
28 | | -cd truf-node-operator |
29 | | -``` |
30 | | - |
31 | | -### 2. Generate Initial Configuration |
32 | | - |
33 | | -Use `kwild` to create your initial configuration file: |
34 | | - |
35 | | -```bash |
36 | | -kwild setup init \ |
37 | | - --genesis ./configs/network/v2/genesis.json \ |
38 | | - --root ./my-node-config \ |
39 | | - --p2p.bootnodes "4e0b5c952be7f26698dc1898ff3696ac30e990f25891aeaf88b0285eab4663e1#ed25519@node-1.mainnet.truf.network:26656,0c830b69790eaa09315826403c2008edc65b5c7132be9d4b7b4da825c2a166ae#ed25519@node-2.mainnet.truf.network:26656" |
40 | | -``` |
41 | | - |
42 | | -For detailed instructions on configuration options more relevant to a production setup, refer to our [Configuration Guide](docs/creating-config.md). |
43 | | - |
44 | | -### 3. Enable State Sync |
45 | | - |
46 | | -Edit the `config.toml` file in your node configuration directory to enable state sync. The following example assumes you used `./my-node-config` as your root directory in the previous step. Adjust the path if you used a different directory: |
47 | | - |
48 | | -```bash |
49 | | -# Edit the config.toml file |
50 | | -sed -i '/\[state_sync\]/,/^\[/ s/enable = false/enable = true/' ./my-node-config/config.toml |
51 | | -sed -i 's/trusted_providers = \[\]/trusted_providers = ["0c830b69790eaa09315826403c2008edc65b5c7132be9d4b7b4da825c2a166ae#ed25519@node-2.mainnet.truf.network:26656"]/' ./my-node-config/config.toml |
52 | | -``` |
53 | | - |
54 | | -This will configure your node to use state sync for faster synchronization with the network. |
55 | | - |
56 | | -### 4. Set Up PostgreSQL |
57 | | - |
58 | | -For a quick setup, run Kwil's pre-configured PostgreSQL Docker image: |
59 | | - |
60 | | -```bash |
61 | | -docker run -d -p 5432:5432 --name tn-postgres \ |
62 | | - -e "POSTGRES_HOST_AUTH_METHOD=trust" \ |
63 | | - -v tn-pgdata:/var/lib/postgresql/data \ |
64 | | - --shm-size=1gb \ |
65 | | - kwildb/postgres:latest |
66 | | -``` |
67 | | - |
68 | | -The command above: |
69 | | -- `-v tn-pgdata:/var/lib/postgresql/data`: Creates a persistent volume named 'tn-pgdata' to store database data |
70 | | -- `--shm-size=1gb`: Allocates 1GB of shared memory for PostgreSQL operations (recommended for better performance) |
71 | | - |
72 | | -#### Installing pg_dump for Snapshots |
73 | | - |
74 | | -To enable state sync functionality, you'll need `pg_dump` installed. Here's how to install it: |
75 | | - |
76 | | -For Ubuntu/Debian: |
77 | | -```bash |
78 | | -sudo apt-get update |
79 | | -sudo apt-get install postgresql-client-16 |
80 | | -``` |
81 | | - |
82 | | -For CentOS/RHEL: |
83 | | -```bash |
84 | | -sudo yum install postgresql16 |
85 | | -``` |
86 | | - |
87 | | -For macOS (using Homebrew): |
88 | | -```bash |
89 | | -brew install postgresql@16 |
90 | | -``` |
91 | | - |
92 | | -Verify the installation: |
93 | | -```bash |
94 | | -pg_dump --version |
95 | | -``` |
96 | | - |
97 | | -This should show PostgreSQL version 16.x.x. The `pg_dump` utility is required for creating and restoring database snapshots during state sync. |
98 | | - |
99 | | -If you prefer a custom PostgreSQL setup, ensure it meets the requirements specified in the [Kwil documentation](https://docs.kwil.com/docs/daemon/running-postgres). |
100 | | - |
101 | | -**Security Warning**: It is recommended to not expose port 5432 publicly in production environments. |
102 | | - |
103 | | -### 5. Deploy TN Node |
104 | | - |
105 | | -Run the kwild binary to deploy your node: |
106 | | - |
107 | | -```bash |
108 | | -kwild start -r ./my-node-config |
109 | | -``` |
110 | | - |
111 | | -You can run kwild in the background by adding `&` at the end of the command: |
112 | | - |
113 | | -```bash |
114 | | -kwild start -r ./my-node-config & |
115 | | -``` |
116 | | - |
117 | | -This allows you to run other kwild commands in the same terminal session, such as checking node status or managing validators. |
118 | | - |
119 | | -Ensure your firewall allows incoming connections on: |
120 | | -- JSON-RPC port (default: 8484) |
121 | | -- P2P port (default: 6600) |
122 | | - |
123 | | -The `--statesync.enable` and `--statesync.trusted_providers` flags are optional and will help your node sync faster with the network using snapshots provided by the RPC servers. |
124 | | - |
125 | | -### 6. Verify Node Synchronization |
126 | | - |
127 | | -Before proceeding to become a validator, ensure your node is fully synced with the network: |
128 | | - |
129 | | -```bash |
130 | | -kwild admin status |
131 | | -``` |
132 | | - |
133 | | -Look for the `syncing: false` in the output, and check that your `best_block_height` is close to the current network height. |
134 | | - |
135 | | -### 7. Become a Validator (Optional) |
136 | | - |
137 | | -To upgrade your node to a validator: |
138 | | - |
139 | | -1. Ensure your node is fully synced with the network. |
140 | | -2. Submit a validator join request: |
141 | | - |
142 | | -```bash |
143 | | -kwild validators join |
144 | | -``` |
145 | | - |
146 | | -3. Wait for approval from existing validators. You can check your join request status with: |
147 | | - |
148 | | -```bash |
149 | | -kwild validators list-join-requests |
150 | | -``` |
151 | | - |
152 | | -Existing validators must approve your request. For each existing validator needed to approve: |
153 | | - |
154 | | -```bash |
155 | | -kwild validators approve <your-node-id> |
156 | | -``` |
157 | | - |
158 | | -The node ID format for validator operations is: `<public key>#<key type>`. For example: |
159 | | -```bash |
160 | | -kwild validators approve 03dbe22b9922b5c0f8f60c230446feaa1c132a93caa9dae83b5d4fab16c3404a22#secp256k1 |
161 | | -``` |
162 | | - |
163 | | -You can find your node's public key and key type by running: |
164 | | -```bash |
165 | | -kwild key info --key-file ./my-node-config/nodekey.json |
166 | | -``` |
167 | | - |
168 | | -Note: If you used a different directory name during setup (not `./my-node-config`), replace the path with your actual node configuration directory path. |
169 | | - |
170 | | -This will show your node's public key and key type, which you'll need for validator operations. |
171 | | - |
172 | | -You can always reach out to the community for help with the validator process. |
173 | | - |
174 | | -### 8. Submit Your Node to Available Node List (Optional) |
175 | | - |
176 | | -To help others discover your node: |
177 | | - |
178 | | -1. Fork the TN repository. |
179 | | -2. Add your node information to the `configs/network/available_nodes.json` file. |
180 | | -3. Submit a Pull Request with your changes. |
181 | | - |
182 | | -We'll review and merge your PR to include your node in the network's seed list. |
183 | | - |
184 | | -## Network Configuration Files |
185 | | - |
186 | | -Essential network configuration files are located in the `configs/network/` directory: |
187 | | - |
188 | | -- `v2/genesis.json`: The network's genesis file. |
189 | | -- `v2/network-nodes.csv`: List of available nodes for peer discovery. |
190 | | - |
191 | | -When setting up your node, refer to these files for network-specific parameters and peer information. |
192 | | - |
193 | | -## Node ID Format |
194 | | - |
195 | | -Node IDs in TRUF.NETWORK follow the format: `<public key>#<key type>@<IP address>:<port>` |
196 | | - |
197 | | -You can find your node ID by running: |
198 | | -```bash |
199 | | -kwild key info --key-file ./my-node-config/nodekey.json |
200 | | -``` |
201 | | - |
202 | | -## Additional Resources |
203 | | - |
204 | | -- [Kwil Documentation](https://docs.kwil.com) |
205 | | -- [Production Network Deployment Guide](https://docs.kwil.com/docs/node/production) |
206 | | - |
207 | | -For further assistance, join our [Discord community](https://discord.com/invite/5AMCBYxfW4) or open an issue on our [GitHub repository](https://github.com/trufnetwork/truf-node-operator/issues). |
| 25 | +For further assistance: |
| 26 | +- Join our [Discord community](https://discord.com/invite/5AMCBYxfW4) |
| 27 | +- Open an issue on this [GitHub repository](https://github.com/trufnetwork/truf-node-operator/issues) |
208 | 28 |
|
209 | 29 | Welcome to the TRUF.NETWORK! Your participation helps build a more robust and decentralized data infrastructure. |
0 commit comments