Skip to content

Commit 6fe18e1

Browse files
MicBunMicBun
committed
docs: add quick start guide
- Add quick start guide for fresh server instances - Add systemd service setup for kwild and PostgreSQL - Add comprehensive log monitoring instructions - Improve troubleshooting section with common commands - Make installation guide more general for any server instance - Add proper service dependencies and auto-restart
1 parent 800db59 commit 6fe18e1

File tree

2 files changed

+205
-0
lines changed

2 files changed

+205
-0
lines changed

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
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.
44

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.
6+
57
## Prerequisites
68

79
Before you begin, ensure you have the following:

‎docs/installation-guide.md‎

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
# TRUF.NETWORK Quick Installation Guide
2+
3+
This guide provides step-by-step instructions for setting up a TRUF.NETWORK node on a fresh Ubuntu installation.
4+
5+
## Prerequisites Installation
6+
7+
Run the following commands to install all required dependencies:
8+
9+
```bash
10+
# 1) Docker Engine & Compose v2 plugin (plus GCC via build-essential)
11+
sudo apt-get update
12+
sudo apt-get install -y ca-certificates curl gnupg lsb-release build-essential
13+
sudo mkdir -p /etc/apt/keyrings
14+
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
15+
| sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
16+
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
17+
https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" \
18+
| sudo tee /etc/apt/sources.list.d/docker.list >/dev/null
19+
sudo apt-get update
20+
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
21+
22+
# 1b) Enable and start Docker
23+
sudo systemctl enable docker
24+
sudo systemctl start docker
25+
26+
# 1c) Add your user to the docker group
27+
sudo usermod -aG docker $USER
28+
29+
# 1d) Install PostgreSQL client (includes pg_dump)
30+
sudo apt-get install -y postgresql-client
31+
32+
# 2) Install Go (required for building kwild)
33+
LATEST_GO_VERSION=$(curl -sSL https://go.dev/VERSION?m=text | head -n1)
34+
echo "Installing ${LATEST_GO_VERSION}..."
35+
curl -fsSL "https://go.dev/dl/${LATEST_GO_VERSION}.linux-amd64.tar.gz" \
36+
-o "${LATEST_GO_VERSION}.linux-amd64.tar.gz"
37+
sudo rm -rf /usr/local/go
38+
sudo tar -C /usr/local -xzf "${LATEST_GO_VERSION}.linux-amd64.tar.gz"
39+
rm "${LATEST_GO_VERSION}.linux-amd64.tar.gz"
40+
41+
# 2b) Add Go to PATH
42+
grep -qxF 'export GOPATH=$HOME/go' ~/.bashrc \
43+
|| echo 'export GOPATH=$HOME/go' >> ~/.bashrc
44+
grep -qxF 'export PATH=$PATH:/usr/local/go/bin:$GOPATH/bin' ~/.bashrc \
45+
|| echo 'export PATH=$PATH:/usr/local/go/bin:$GOPATH/bin' >> ~/.bashrc
46+
47+
# 3) Reload your shell
48+
source ~/.bashrc
49+
50+
# 4) Install Taskfile (go-task)
51+
go install github.com/go-task/task/v3/cmd/task@latest
52+
53+
# 5) Clone the node repository and build kwild
54+
git clone https://github.com/trufnetwork/node.git
55+
cd node
56+
task build
57+
58+
# 6) Add the built kwild binary to PATH
59+
sudo cp .build/kwild /usr/local/bin/
60+
sudo chmod +x /usr/local/bin/kwild
61+
62+
# 7) Apply new docker group immediately
63+
newgrp docker
64+
```
65+
66+
## Verify Installation
67+
68+
Verify that everything is installed correctly:
69+
70+
```bash
71+
docker --version
72+
docker compose version
73+
pg_dump --version
74+
go version
75+
task --version
76+
kwild version
77+
```
78+
79+
## Node Setup
80+
81+
Now that you have all prerequisites installed, follow these steps to set up your node:
82+
83+
```bash
84+
# 1) Go to home directory
85+
cd
86+
87+
# 2) Clone the TRUF.NETWORK node operator repository
88+
git clone https://github.com/trufnetwork/truf-node-operator.git
89+
cd truf-node-operator
90+
91+
# 3) Generate initial configuration
92+
kwild setup init \
93+
--genesis ./configs/network/v2/genesis.json \
94+
--root ./my-node-config \
95+
--p2p.bootnodes "4e0b5c952be7f26698dc1898ff3696ac30e990f25891aeaf88b0285eab4663e1#ed25519@node-1.mainnet.truf.network:26656,0c830b69790eaa09315826403c2008edc65b5c7132be9d4b7b4da825c2a166ae#ed25519@node-2.mainnet.truf.network:26656"
96+
97+
# 4) Enable state sync (for faster synchronization)
98+
sed -i '/\[state_sync\]/,/^\[/ s/enable = false/enable = true/' ./my-node-config/config.toml
99+
sed -i 's/trusted_providers = \[\]/trusted_providers = ["0c830b69790eaa09315826403c2008edc65b5c7132be9d4b7b4da825c2a166ae#ed25519@node-2.mainnet.truf.network:26656"]/' ./my-node-config/config.toml
100+
101+
# 5) Set up PostgreSQL using Docker
102+
docker run -d -p 5432:5432 --name tn-postgres \
103+
-e "POSTGRES_HOST_AUTH_METHOD=trust" \
104+
-v tn-pgdata:/var/lib/postgresql/data \
105+
--shm-size=1gb \
106+
kwildb/postgres:latest
107+
108+
# 5b) Wait for PostgreSQL to initialize
109+
echo "Waiting for PostgreSQL to initialize..."
110+
sleep 10
111+
112+
# 6) Create systemd service for kwild
113+
sudo tee /etc/systemd/system/kwild.service << EOF
114+
[Unit]
115+
Description=TRUF.NETWORK Node Service
116+
After=network.target tn-postgres.service
117+
Requires=tn-postgres.service
118+
119+
[Service]
120+
Type=simple
121+
User=$USER
122+
WorkingDirectory=$(pwd)
123+
ExecStart=$(which kwild) start -r ./my-node-config
124+
Restart=always
125+
RestartSec=10
126+
LimitNOFILE=65535
127+
128+
[Install]
129+
WantedBy=multi-user.target
130+
EOF
131+
132+
# 7) Create systemd service for PostgreSQL
133+
sudo tee /etc/systemd/system/tn-postgres.service << EOF
134+
[Unit]
135+
Description=TRUF.NETWORK PostgreSQL Service
136+
After=docker.service
137+
Requires=docker.service
138+
139+
[Service]
140+
Type=simple
141+
User=$USER
142+
ExecStart=docker start -a tn-postgres
143+
ExecStop=docker stop tn-postgres
144+
Restart=always
145+
RestartSec=10
146+
147+
[Install]
148+
WantedBy=multi-user.target
149+
EOF
150+
151+
# 8) Enable and start services
152+
sudo systemctl daemon-reload
153+
sudo systemctl enable tn-postgres
154+
sudo systemctl enable kwild
155+
sudo systemctl start tn-postgres
156+
sudo systemctl start kwild
157+
158+
# 9) Check service status
159+
echo "Checking service status..."
160+
sudo systemctl status kwild
161+
```
162+
163+
## Check Node Status
164+
165+
To check if your node is running properly:
166+
167+
```bash
168+
# Check service status
169+
sudo systemctl status kwild
170+
171+
# Check node status
172+
kwild admin status
173+
```
174+
175+
Your node is fully synced when you see `syncing: false` and your `best_block_height` is close to the current network height.
176+
177+
## Troubleshooting
178+
179+
If you encounter any issues:
180+
181+
1. Check service status: `sudo systemctl status kwild`
182+
2. Watch logs in real-time: `sudo journalctl -u kwild -f`
183+
- Press `Ctrl+C` to stop watching
184+
3. Check Docker container status: `docker ps`
185+
4. Check PostgreSQL logs: `docker logs tn-postgres`
186+
187+
### Common Commands
188+
189+
```bash
190+
# Watch kwild logs in real-time
191+
sudo journalctl -u kwild -f
192+
193+
# Watch last 100 lines of logs
194+
sudo journalctl -u kwild -n 100
195+
196+
# Watch logs since last boot
197+
sudo journalctl -u kwild -b
198+
199+
# Watch logs with timestamps
200+
sudo journalctl -u kwild -f --output=short-precise
201+
```
202+
203+
For more detailed configuration options and validator setup, refer to the main [README.md](../README.md).

0 commit comments

Comments
 (0)