🔌 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 "[e-mail]:26656,[e-mail]: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: https://docs.gno.land/builders/install/

• Gno.land getting started: https://docs.gno.land/builders/getting-started/

• Gno.land networks: https://docs.gno.land/resources/gnoland-networks/

• Gno.land GitHub repository: https://github.com/gnolang/gno

• Topaz setup reference: https://guides.hazennetworksolutions.com/gnoland/