From 18edf685633ea5d8b88a50ef370d9d224127ce45 Mon Sep 17 00:00:00 2001 From: Michael Buntarman Date: Fri, 30 May 2025 16:45:51 +0700 Subject: [PATCH 1/2] docs: remove detailed guide and links to official docs --- README.md | 212 +++---------------------------------- docs/installation-guide.md | 208 ------------------------------------ 2 files changed, 16 insertions(+), 404 deletions(-) delete mode 100644 docs/installation-guide.md diff --git a/README.md b/README.md index 62ee19e..891cabc 100644 --- a/README.md +++ b/README.md @@ -1,209 +1,29 @@ # TRUF.NETWORK Node Operator Guide -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. +This repository contains configuration files and utilities for running a TRUF.NETWORK (TN) node. -> **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. +## Documentation -## Prerequisites +For detailed instructions on setting up and running a TRUF.NETWORK node, please refer to our official documentation: -Before you begin, ensure you have the following: +- [Node Operator Guide](https://trufnetwork.github.io/node-operator-guide) - Comprehensive guide to setting up and running a TN node -1. **Kwild**: The all-in-one binary for node operation and administration. - - Download from the [latest GitHub release](https://github.com/trufnetwork/node/releases) +## Repository Contents -2. **Docker**: Required for running the PostgreSQL image. - - Install from [Docker's official website](https://docs.docker.com/get-docker) +This repository contains: -3. **PostgreSQL Client**: Required for state sync and database operations. - - Install with `sudo apt -y install postgresql-16` (Ubuntu/Debian) +1. **Configuration Files**: Essential network configuration files in the `configs/network/` directory: + - `v2/genesis.json`: The network's genesis file + - `v2/network-nodes.csv`: List of available nodes for peer discovery -## Setup Steps +2. **Documentation**: Detailed guides in the `docs/` directory: + - `installation-guide.md`: Quick start guide with copy-paste commands + - `creating-config.md`: Detailed configuration options for production setups -### 1. Clone the Repository +## Getting Help -First, clone the TRUF.NETWORK node operator repository: - -```bash -git clone https://github.com/trufnetwork/truf-node-operator.git -cd truf-node-operator -``` - -### 2. Generate Initial Configuration - -Use `kwild` to create your initial configuration file: - -```bash -kwild setup init \ - --genesis ./configs/network/v2/genesis.json \ - --root ./my-node-config \ - --p2p.bootnodes "4e0b5c952be7f26698dc1898ff3696ac30e990f25891aeaf88b0285eab4663e1#ed25519@node-1.mainnet.truf.network:26656,0c830b69790eaa09315826403c2008edc65b5c7132be9d4b7b4da825c2a166ae#ed25519@node-2.mainnet.truf.network:26656" -``` - -For detailed instructions on configuration options more relevant to a production setup, refer to our [Configuration Guide](docs/creating-config.md). - -### 3. Enable State Sync - -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: - -```bash -# Edit the config.toml file -sed -i '/\[state_sync\]/,/^\[/ s/enable = false/enable = true/' ./my-node-config/config.toml -sed -i 's/trusted_providers = \[\]/trusted_providers = ["0c830b69790eaa09315826403c2008edc65b5c7132be9d4b7b4da825c2a166ae#ed25519@node-2.mainnet.truf.network:26656"]/' ./my-node-config/config.toml -``` - -This will configure your node to use state sync for faster synchronization with the network. - -### 4. Set Up PostgreSQL - -For a quick setup, run Kwil's pre-configured PostgreSQL Docker image: - -```bash -docker run -d -p 5432:5432 --name tn-postgres \ - -e "POSTGRES_HOST_AUTH_METHOD=trust" \ - -v tn-pgdata:/var/lib/postgresql/data \ - --shm-size=1gb \ - kwildb/postgres:latest -``` - -The command above: -- `-v tn-pgdata:/var/lib/postgresql/data`: Creates a persistent volume named 'tn-pgdata' to store database data -- `--shm-size=1gb`: Allocates 1GB of shared memory for PostgreSQL operations (recommended for better performance) - -#### Installing pg_dump for Snapshots - -To enable state sync functionality, you'll need `pg_dump` installed. Here's how to install it: - -For Ubuntu/Debian: -```bash -sudo apt-get update -sudo apt-get install postgresql-client-16 -``` - -For CentOS/RHEL: -```bash -sudo yum install postgresql16 -``` - -For macOS (using Homebrew): -```bash -brew install postgresql@16 -``` - -Verify the installation: -```bash -pg_dump --version -``` - -This should show PostgreSQL version 16.x.x. The `pg_dump` utility is required for creating and restoring database snapshots during state sync. - -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). - -**Security Warning**: It is recommended to not expose port 5432 publicly in production environments. - -### 5. Deploy TN Node - -Run the kwild binary to deploy your node: - -```bash -kwild start -r ./my-node-config -``` - -You can run kwild in the background by adding `&` at the end of the command: - -```bash -kwild start -r ./my-node-config & -``` - -This allows you to run other kwild commands in the same terminal session, such as checking node status or managing validators. - -Ensure your firewall allows incoming connections on: -- JSON-RPC port (default: 8484) -- P2P port (default: 6600) - -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. - -### 6. Verify Node Synchronization - -Before proceeding to become a validator, ensure your node is fully synced with the network: - -```bash -kwild admin status -``` - -Look for the `syncing: false` in the output, and check that your `best_block_height` is close to the current network height. - -### 7. Become a Validator (Optional) - -To upgrade your node to a validator: - -1. Ensure your node is fully synced with the network. -2. Submit a validator join request: - -```bash -kwild validators join -``` - -3. Wait for approval from existing validators. You can check your join request status with: - -```bash -kwild validators list-join-requests -``` - -Existing validators must approve your request. For each existing validator needed to approve: - -```bash -kwild validators approve -``` - -The node ID format for validator operations is: `#`. For example: -```bash -kwild validators approve 03dbe22b9922b5c0f8f60c230446feaa1c132a93caa9dae83b5d4fab16c3404a22#secp256k1 -``` - -You can find your node's public key and key type by running: -```bash -kwild key info --key-file ./my-node-config/nodekey.json -``` - -Note: If you used a different directory name during setup (not `./my-node-config`), replace the path with your actual node configuration directory path. - -This will show your node's public key and key type, which you'll need for validator operations. - -You can always reach out to the community for help with the validator process. - -### 8. Submit Your Node to Available Node List (Optional) - -To help others discover your node: - -1. Fork the TN repository. -2. Add your node information to the `configs/network/available_nodes.json` file. -3. Submit a Pull Request with your changes. - -We'll review and merge your PR to include your node in the network's seed list. - -## Network Configuration Files - -Essential network configuration files are located in the `configs/network/` directory: - -- `v2/genesis.json`: The network's genesis file. -- `v2/network-nodes.csv`: List of available nodes for peer discovery. - -When setting up your node, refer to these files for network-specific parameters and peer information. - -## Node ID Format - -Node IDs in TRUF.NETWORK follow the format: `#@:` - -You can find your node ID by running: -```bash -kwild key info --key-file ./my-node-config/nodekey.json -``` - -## Additional Resources - -- [Kwil Documentation](https://docs.kwil.com) -- [Production Network Deployment Guide](https://docs.kwil.com/docs/node/production) - -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). +For further assistance: +- Join our [Discord community](https://discord.com/invite/5AMCBYxfW4) +- Open an issue on this [GitHub repository](https://github.com/trufnetwork/truf-node-operator/issues) Welcome to the TRUF.NETWORK! Your participation helps build a more robust and decentralized data infrastructure. diff --git a/docs/installation-guide.md b/docs/installation-guide.md deleted file mode 100644 index bd7269a..0000000 --- a/docs/installation-guide.md +++ /dev/null @@ -1,208 +0,0 @@ -# TRUF.NETWORK Quick Installation Guide - -This guide provides step-by-step instructions for setting up a TRUF.NETWORK node on a fresh server instance. While the commands are written for Ubuntu, they can be adapted for other Linux distributions with minimal changes. - -> **Note**: This guide uses Ubuntu-specific package managers (`apt-get`) and paths. If you're using a different Linux distribution: -> - Replace `apt-get` with your distribution's package manager (e.g., `yum` for RHEL/CentOS, `dnf` for Fedora) -> - Adjust package names if they differ in your distribution -> - The core concepts and steps remain the same - -## Prerequisites Installation - -Run the following commands to install all required dependencies: - -```bash -# 1) Docker Engine & Compose v2 plugin (plus GCC via build-essential) -sudo apt-get update -sudo apt-get install -y ca-certificates curl gnupg lsb-release build-essential -sudo mkdir -p /etc/apt/keyrings -curl -fsSL https://download.docker.com/linux/ubuntu/gpg \ - | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg -echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \ - https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" \ - | sudo tee /etc/apt/sources.list.d/docker.list >/dev/null -sudo apt-get update -sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin - -# 1b) Enable and start Docker -sudo systemctl enable docker -sudo systemctl start docker - -# 1c) Add your user to the docker group -sudo usermod -aG docker $USER - -# 1d) Install PostgreSQL client (includes pg_dump) -sudo apt-get install -y postgresql-client - -# 2) Install Go (required for building kwild) -LATEST_GO_VERSION=$(curl -sSL https://go.dev/VERSION?m=text | head -n1) -echo "Installing ${LATEST_GO_VERSION}..." -curl -fsSL "https://go.dev/dl/${LATEST_GO_VERSION}.linux-amd64.tar.gz" \ - -o "${LATEST_GO_VERSION}.linux-amd64.tar.gz" -sudo rm -rf /usr/local/go -sudo tar -C /usr/local -xzf "${LATEST_GO_VERSION}.linux-amd64.tar.gz" -rm "${LATEST_GO_VERSION}.linux-amd64.tar.gz" - -# 2b) Add Go to PATH -grep -qxF 'export GOPATH=$HOME/go' ~/.bashrc \ - || echo 'export GOPATH=$HOME/go' >> ~/.bashrc -grep -qxF 'export PATH=$PATH:/usr/local/go/bin:$GOPATH/bin' ~/.bashrc \ - || echo 'export PATH=$PATH:/usr/local/go/bin:$GOPATH/bin' >> ~/.bashrc - -# 3) Reload your shell -source ~/.bashrc - -# 4) Install Taskfile (go-task) -go install github.com/go-task/task/v3/cmd/task@latest - -# 5) Clone the node repository and build kwild -git clone https://github.com/trufnetwork/node.git -cd node -task build - -# 6) Add the built kwild binary to PATH -sudo cp .build/kwild /usr/local/bin/ -sudo chmod +x /usr/local/bin/kwild - -# 7) Apply new docker group immediately -newgrp docker -``` - -## Verify Installation - -Verify that everything is installed correctly: - -```bash -docker --version -docker compose version -pg_dump --version -go version -task --version -kwild version -``` - -## Node Setup - -Now that you have all prerequisites installed, follow these steps to set up your node: - -```bash -# 1) Go to home directory -cd - -# 2) Clone the TRUF.NETWORK node operator repository -git clone https://github.com/trufnetwork/truf-node-operator.git -cd truf-node-operator - -# 3) Generate initial configuration -kwild setup init \ - --genesis ./configs/network/v2/genesis.json \ - --root ./my-node-config \ - --p2p.bootnodes "4e0b5c952be7f26698dc1898ff3696ac30e990f25891aeaf88b0285eab4663e1#ed25519@node-1.mainnet.truf.network:26656,0c830b69790eaa09315826403c2008edc65b5c7132be9d4b7b4da825c2a166ae#ed25519@node-2.mainnet.truf.network:26656" - -# 4) Enable state sync (for faster synchronization) -sed -i '/\[state_sync\]/,/^\[/ s/enable = false/enable = true/' ./my-node-config/config.toml -sed -i 's/trusted_providers = \[\]/trusted_providers = ["0c830b69790eaa09315826403c2008edc65b5c7132be9d4b7b4da825c2a166ae#ed25519@node-2.mainnet.truf.network:26656"]/' ./my-node-config/config.toml - -# 5) Set up PostgreSQL using Docker -docker run -d -p 5432:5432 --name tn-postgres \ - -e "POSTGRES_HOST_AUTH_METHOD=trust" \ - -v tn-pgdata:/var/lib/postgresql/data \ - --shm-size=1gb \ - kwildb/postgres:latest - -# 5b) Wait for PostgreSQL to initialize -echo "Waiting for PostgreSQL to initialize..." -sleep 10 - -# 6) Create systemd service for kwild -sudo tee /etc/systemd/system/kwild.service << EOF -[Unit] -Description=TRUF.NETWORK Node Service -After=network.target tn-postgres.service -Requires=tn-postgres.service - -[Service] -Type=simple -User=$USER -WorkingDirectory=$(pwd) -ExecStart=$(which kwild) start -r ./my-node-config -Restart=always -RestartSec=10 -LimitNOFILE=65535 - -[Install] -WantedBy=multi-user.target -EOF - -# 7) Create systemd service for PostgreSQL -sudo tee /etc/systemd/system/tn-postgres.service << EOF -[Unit] -Description=TRUF.NETWORK PostgreSQL Service -After=docker.service -Requires=docker.service - -[Service] -Type=simple -User=$USER -ExecStart=docker start -a tn-postgres -ExecStop=docker stop tn-postgres -Restart=always -RestartSec=10 - -[Install] -WantedBy=multi-user.target -EOF - -# 8) Enable and start services -sudo systemctl daemon-reload -sudo systemctl enable tn-postgres -sudo systemctl enable kwild -sudo systemctl start tn-postgres -sudo systemctl start kwild - -# 9) Check service status -echo "Checking service status..." -sudo systemctl status kwild -``` - -## Check Node Status - -To check if your node is running properly: - -```bash -# Check service status -sudo systemctl status kwild - -# Check node status -kwild admin status -``` - -Your node is fully synced when you see `syncing: false` and your `best_block_height` is close to the current network height. - -## Troubleshooting - -If you encounter any issues: - -1. Check service status: `sudo systemctl status kwild` -2. Watch logs in real-time: `sudo journalctl -u kwild -f` - - Press `Ctrl+C` to stop watching -3. Check Docker container status: `docker ps` -4. Check PostgreSQL logs: `docker logs tn-postgres` - -### Common Commands - -```bash -# Watch kwild logs in real-time -sudo journalctl -u kwild -f - -# Watch last 100 lines of logs -sudo journalctl -u kwild -n 100 - -# Watch logs since last boot -sudo journalctl -u kwild -b - -# Watch logs with timestamps -sudo journalctl -u kwild -f --output=short-precise -``` - -For more detailed configuration options and validator setup, refer to the main [README.md](../README.md). \ No newline at end of file From 4265a4c0b7f495232132ea5d556752176f453436 Mon Sep 17 00:00:00 2001 From: Michael Buntarman Date: Fri, 30 May 2025 17:12:07 +0700 Subject: [PATCH 2/2] docs: change the link into docs@node-operator-guide --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 891cabc..a02c7b3 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ This repository contains configuration files and utilities for running a TRUF.NE For detailed instructions on setting up and running a TRUF.NETWORK node, please refer to our official documentation: -- [Node Operator Guide](https://trufnetwork.github.io/node-operator-guide) - Comprehensive guide to setting up and running a TN node +- [Node Operator Guide](https://docs.truf.network/node-operator-guide) - Comprehensive guide to setting up and running a TN node ## Repository Contents