> For the complete documentation index, see [llms.txt](https://services.noderuner.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://services.noderuner.xyz/gno.land-topaz/installation.md).
# 🔌 Installation
## Gno.land Topaz Node Setup Guide
This guide covers how to set up a Gno.land Topaz full node on an Ubuntu VPS, create a systemd service, and maintain the node with useful day-to-day commands.
> Note: Topaz testnet parameters may change over time. Before installing, verify the current `chain_id`, genesis file, branch, and peer information from official Gno.land sources or the latest network announcements.
### Overview
```
Network: Gno.land Topaz
Chain ID: topaz-1
P2P Port: 26656
Local RPC: 127.0.0.1:26657
Branch: chain/topaz
Data path: /root/gno/gnoland-data
```
This guide does not expose RPC publicly. RPC is kept local on `127.0.0.1:26657`. For external network connectivity, only the P2P port `26656/tcp` is required.
### Server Requirements
Recommended minimum:
```
CPU: 4 cores
RAM: 8 GB
Disk: 200 GB+ SSD
OS: Ubuntu 22.04 / 24.04
Network: 100 Mbps+
```
### Environment Variables
The guide uses the following variables:
```
export MONIKER="node-moniker"
export CHAIN_ID="topaz-1"
export GNO_HOME="/root/gno"
export GNO_DATA="/root/gno/gnoland-data"
export GO_VERSION="1.25.12"
```
Replace `MONIKER` with your own node name.
### 1. Prepare the System
Update the server:
```
apt update
apt upgrade -y
```
Install required packages:
```
apt install -y curl wget git jq lz4 unzip tar build-essential make gcc chrony ca-certificates
```
Enable time synchronization:
```
systemctl enable --now chrony
chronyc tracking
```
### 2. Configure Firewall
If you use UFW, allow SSH and the P2P port:
```
apt install -y ufw
ufw allow OpenSSH
ufw allow 26656/tcp
ufw enable
ufw status
```
Do not expose the RPC port publicly:
```
# 26657/tcp should not be opened publicly
```
### 3. Install Go
Remove any old Go installation:
```
rm -rf /usr/local/go
```
Download and install Go:
```
cd /root
wget "https://golang.org/dl/go${GO_VERSION}.linux-amd64.tar.gz"
tar -C /usr/local -xzf "go${GO_VERSION}.linux-amd64.tar.gz"
rm "go${GO_VERSION}.linux-amd64.tar.gz"
```
Add Go and Gno paths:
```
echo 'export PATH=/usr/local/go/bin:$HOME/go/bin:$PATH' >> ~/.bashrc
echo 'export GNOROOT=$HOME/gno' >> ~/.bashrc
source ~/.bashrc
```
Verify the installation:
```
go version
```
### 4. Build Gno From Source
Clone the repository:
```
cd /root
git clone https://github.com/gnolang/gno.git
cd /root/gno
git checkout chain/topaz
```
Build the binaries:
```
make install
make -C gno.land install.gnoland
make -C contribs/gnogenesis install
```
Verify the binaries:
```
which gnoland
which gnokey
gnoland version
gnokey version
```
The expected `gnoland` binary path is usually:
```
/root/go/bin/gnoland
```
### 5. Prepare Genesis and Initial Data
If an old or broken node data directory exists, make sure the service is stopped first:
```
systemctl stop gnoland 2>/dev/null || true
```
Download the Topaz genesis file:
```
cd /root/gno
rm -rf gnoland-data genesis.json
wget -O genesis.json https://github.com/gnolang/gno/releases/download/chain/topaz/genesis.json
```
Check the genesis hash:
```
shasum -a 256 genesis.json
```
Genesis hash used by current setup references:
```
2dd049f973b82858727440df9aff5722cb0b322fd00890f40f2b0688276898ff genesis.json
```
Initialize node config and secrets:
```
cd /root/gno
gnoland secrets init
gnoland config init
```
### 6. Configure the Node
Set your moniker and the main node parameters:
```
cd /root/gno
gnoland config set moniker "$MONIKER"
gnoland config set application.prune_strategy syncable
gnoland config set consensus.timeout_commit 3s
gnoland config set consensus.peer_gossip_sleep_duration 10ms
gnoland config set p2p.flush_throttle_timeout 10ms
gnoland config set p2p.pex true
gnoland config set p2p.max_num_outbound_peers 40
gnoland config set mempool.size 10000
gnoland config set telemetry.metrics_enabled false
gnoland config set p2p.laddr "tcp://0.0.0.0:26656"
gnoland config set rpc.laddr "tcp://127.0.0.1:26657"
gnoland config set p2p.external_address "YOUR-SERVER-IP:26656"
gnoland config set p2p.persistent_peers "g19q07ssuafhmg6r7ys7wp7rpc4jxc85cpvdy426@seed-1.topaz.testnets.gno.land:26656,g15k98e65gm8h7fdr3yr4tqn82lvch4a97a3sg3j@seed-2.topaz.testnets.gno.land:26656"
```
Replace `YOUR-SERVER-IP` with your VPS public IP address.
Check the config:
```
grep -n "^\[p2p\]\|^\[rpc\]\|laddr\|external_address\|persistent_peers" /root/gno/gnoland-data/config/config.toml
```
RPC should remain local:
```
laddr = "tcp://127.0.0.1:26657"
```
P2P should listen publicly:
```
laddr = "tcp://0.0.0.0:26656"
```
### 7. Test Manual Startup
Before creating the service, run a short manual test:
```
cd /root/gno
gnoland start \
--chainid topaz-1 \
--genesis /root/gno/genesis.json \
--skip-genesis-sig-verification
```
In another SSH session, check the local RPC:
```
curl -s http://127.0.0.1:26657/status | jq
```
If it works, stop the manually running node with `CTRL + C`.
### 8. Create a Systemd Service
Create the service file:
```
nano /etc/systemd/system/gnoland.service
```
Service file:
```
[Unit]
Description=Gno.land Topaz Node
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=root
Group=root
WorkingDirectory=/root/gno
Environment=GNOROOT=/root/gno
Environment=HOME=/root
ExecStart=/root/go/bin/gnoland start --chainid topaz-1 --genesis /root/gno/genesis.json --skip-genesis-sig-verification
Restart=on-failure
RestartSec=5
LimitNOFILE=65535
StandardOutput=journal
StandardError=journal
SyslogIdentifier=gnoland
[Install]
WantedBy=multi-user.target
```
Enable and start the service:
```
systemctl daemon-reload
systemctl enable gnoland
systemctl start gnoland
```
Check the service status:
```
systemctl status gnoland
```
Follow live logs:
```
journalctl -u gnoland -f --no-hostname -o cat
```
### 9. Check Sync and Node Status
RPC status:
```
curl -s http://127.0.0.1:26657/status | jq
```
Sync status:
```
curl -s http://127.0.0.1:26657/status | jq '.result.sync_info'
```
Latest block height:
```
curl -s http://127.0.0.1:26657/status | jq -r '.result.sync_info.latest_block_height'
```
Peer count:
```
curl -s http://127.0.0.1:26657/net_info | jq '.result.n_peers'
```
Validator set:
```
curl -s http://127.0.0.1:26657/validators | jq
```
### 10. Useful Service Commands
Start the node:
```
systemctl start gnoland
```
Stop the node:
```
systemctl stop gnoland
```
Restart the node:
```
systemctl restart gnoland
```
Check service status:
```
systemctl status gnoland
```
Follow live logs:
```
journalctl -u gnoland -f --no-hostname -o cat
```
Show the last 100 log lines:
```
journalctl -u gnoland -n 100 --no-pager
```
Enable the service on boot:
```
systemctl enable gnoland
```
Disable the service on boot:
```
systemctl disable gnoland
```
### 11. Useful Node Commands
Check the binary:
```
which gnoland
gnoland version
```
Check ports:
```
ss -tulpn | grep -E '26656|26657'
```
Show node ID:
```
gnoland secrets get node_id
```
Show validator public key:
```
cd /root/gno
gnoland secrets get validator_key
```
View node config:
```
cat /root/gno/gnoland-data/config/config.toml
```
Quickly check P2P and RPC settings:
```
grep -n "^\[p2p\]\|^\[rpc\]\|laddr\|external_address\|persistent_peers" /root/gno/gnoland-data/config/config.toml
```
### 12. Log and Disk Maintenance
Check disk usage:
```
df -h
du -h --max-depth=1 /var 2>/dev/null | sort -h
du -h --max-depth=1 /var/log 2>/dev/null | sort -h
```
Find the largest log files:
```
find /var/log -maxdepth 1 -type f -printf '%s %p\n' 2>/dev/null | sort -nr | head -20
```
Check journal usage:
```
journalctl --disk-usage
```
Configure journald limits:
```
nano /etc/systemd/journald.conf
```
Keep these values active:
```
[Journal]
Storage=auto
Compress=yes
SystemMaxUse=500M
RuntimeMaxUse=100M
MaxRetentionSec=3day
```
Apply the changes:
```
systemctl restart systemd-journald
journalctl --vacuum-size=200M
```
### 13. Update the Node
Stop the service before updating:
```
systemctl stop gnoland
```
Update the source code:
```
cd /root/gno
git fetch --all --tags
git checkout chain/topaz
git pull
```
Rebuild the binaries:
```
make install
make -C gno.land install.gnoland
make -C contribs/gnogenesis install
```
Verify the version:
```
gnoland version
```
Start the service:
```
systemctl start gnoland
journalctl -u gnoland -f --no-hostname -o cat
```
### 14. Backup
Back up config and secret files:
```
mkdir -p /root/backups
tar -czf /root/backups/gnoland-config-$(date +%F).tar.gz \
/root/gno/gnoland-data/config \
/root/gno/gnoland-data/secrets \
/root/gno/genesis.json
```
Download the backup to another machine:
```
scp root@SERVER_IP:/root/backups/gnoland-config-YYYY-MM-DD.tar.gz .
```
### 15. Quick Troubleshooting
If the node does not start:
```
systemctl status gnoland
journalctl -u gnoland -n 100 --no-pager
```
If RPC does not respond:
```
curl -s http://127.0.0.1:26657/status | jq
ss -tulpn | grep 26657
```
If there are no peers:
```
curl -s http://127.0.0.1:26657/net_info | jq '.result.n_peers'
grep -n "persistent_peers\|external_address" /root/gno/gnoland-data/config/config.toml
```
If the disk is full:
```
df -h
du -h --max-depth=1 /var/log 2>/dev/null | sort -h
journalctl --vacuum-size=200M
```
After changing the config:
```
systemctl restart gnoland
```
### Sources
* Gno.land official installation docs:
* Gno.land getting started:
* Gno.land networks:
* Gno.land GitHub repository:
* Topaz setup reference: