Skip to content

Run a Bitcoin Gold full node

A full node validates every block and transaction against Bitcoin Gold's consensus rules, supports the network by relaying blocks, and gives you a trustless view of the chain. This course takes you from a fresh Ubuntu 22.04 / 24.04 install to a hardened, monitored, systemd-managed Bitcoin Gold full node.

This walkthrough is written for bgoldd v0.17.3 and uses a tested reference configuration.

Who this is for

You should be comfortable with:

  • Basic Linux command line (cd, apt, systemctl, cat, nano).
  • Opening firewall ports and reading a config file.
  • The concept of "trustless validation" — you don't need to trust any third party to tell you your balance is correct.

If you prefer to install from a prebuilt binary instead of compiling, see Building from source for the compile path; everything below works the same.

What you'll build

By the end of this course you will have:

  • A compiled bgoldd binary at /usr/local/bin/bgoldd.
  • A dedicated bitcoingold system user running the daemon.
  • A bitcoingold.conf that binds RPC to localhost only and exposes P2P on 8338.
  • A systemd unit (btgd.service) that auto-restarts on failure.
  • A ufw rule allowing inbound P2P, blocking RPC from the network.
  • A logrotate policy keeping debug.log under control.
  • Verification commands that cross-check your chain tip against the public explorer.

Requirements

Resource Minimum Recommended (mainnet sync in <24 h)
OS Ubuntu 22.04 LTS Ubuntu 22.04 / 24.04 LTS
CPU 2 cores 4+ cores
RAM 4 GB 8 GB
Disk 200 GB SSD 500 GB SSD (txindex grows quickly)
Bandwidth 5 TB/month 10 TB/month (sustained relay)
Time (initial sync) Hardware-dependent Faster storage and more cache reduce synchronization time

1. Install build dependencies

sudo apt update
sudo apt install -y build-essential libtool autotools-dev automake \
  pkg-config libssl-dev libevent-dev bsdmainutils libboost-all-dev \
  libminiupnpc-dev libzmq3-dev libdb-dev libdb++-dev

If you also want the GUI wallet:

sudo apt install -y libqt5gui5 libqt5core5a libqt5dbus5 qttools5-dev qttools5-dev-tools

2. Clone the source

cd /usr/local/src
sudo git clone https://github.com/BTCGPU/BTCGPU.git
sudo chown -R "$USER:$USER" BTCGPU
cd BTCGPU
git log --oneline -1   # note the commit for later reference

3. Build

The full build (no GUI) takes ~10–25 minutes on a 4-core machine.

./autogen.sh
./configure --without-gui --with-incompatible-bips
make -j"$(nproc)"

Common configure flags

  • --with-gui — build the Qt5 wallet (bitcoin-qt).
  • --disable-wallet — node only, no wallet.dat, smaller attack surface.
  • --with-incompatible-bips — enable BIPs that Bitcoin Gold adopted but BTC has not.
  • --prefix=/usr/local — install location (default).

If make fails on libdb (Berkeley DB), install libdb++-dev and re-run ./configure.

4. Install

sudo make install
which bgoldd
bgoldd --version

You should see something like Bitcoin Gold Core version v0.17.3.

5. Create the data directory and system user

sudo useradd --system --home /var/lib/bitcoingold --shell /usr/sbin/nologin bitcoingold
sudo mkdir -p /var/lib/bitcoingold/.bitcoingold
sudo chown -R bitcoingold:bitcoingold /var/lib/bitcoingold

Why /var/lib/bitcoingold?

Putting the data directory under /var/lib follows the Filesystem Hierarchy Standard. It's where other daemons (PostgreSQL, MariaDB) keep their data, so backups and monitoring tools know to look.

6. Write bitcoingold.conf

This reference configuration uses conservative defaults. The values are explained inline.

sudo tee /var/lib/bitcoingold/.bitcoingold/bitcoingold.conf > /dev/null <<'EOF'
# Bitcoin Gold full node
# ------------------------------
# server=1            : accept RPC commands
# txindex=1           : maintain a full transaction index (required for explorers)
# listen=1            : accept inbound P2P connections
# port=8338           : Bitcoin Gold P2P port (NOT 8333 — that's Bitcoin)
# discover=1          : discover addresses this node can advertise to peers
# uacomment=...       : adds an optional label to the peer user agent
server=1
txindex=1
listen=1
port=8338
discover=1
uacomment=community-node

# Data directory (default, but explicit is better)
datadir=/var/lib/bitcoingold/.bitcoingold/

# Logging: send output to the systemd journal
printtoconsole=1
nodebuglogfile=1

# RPC: bind to localhost only — never expose RPC to the network
rpcbind=127.0.0.1
rpcallowip=127.0.0.1
rpcport=8332

# Replace these with strong random values:
#   tr -dc 'A-Za-z0-9' </dev/urandom | head -c 32 ; echo
rpcuser=RPC_USER
rpcpassword=CHANGE_ME_LONG_RANDOM

# Bitcoin BIP-61 peer messaging is opt-in for Bitcoin Gold; disable to reduce log noise
enablebip61=0

# IPv4 only, no Tor (turn back on if you run a hidden service)
onlynet=ipv4
listenonion=0

# Use DNS seeds to discover initial peers
dnsseed=1

# ZMQ: Blockbook consumes hashblock events on 127.0.0.1:38335
zmqpubhashblock=tcp://127.0.0.1:38335

# Total inbound and outbound connection limit
maxconnections=125
maxuploadtarget=0    # no upload cap (saturate the link; helps the network)

# Database cache in MB. 2000 is a sweet spot for 8 GB RAM nodes.
dbcache=2000

# Run as a node only; we use ElectrumG/Blockbook for the wallet side
disablewallet=1
EOF

sudo chown bitcoingold:bitcoingold /var/lib/bitcoingold/.bitcoingold/bitcoingold.conf
sudo chmod 600 /var/lib/bitcoingold/.bitcoingold/bitcoingold.conf

Lock the config file down

chmod 600 is mandatory because the file contains your RPC password in plaintext. Anyone who obtains it can control the node through RPC and, if wallet functionality is enabled, may be able to spend funds.

7. Create the systemd unit

sudo tee /etc/systemd/system/btgd.service > /dev/null <<'EOF'
[Unit]
Description=Bitcoin Gold Daemon
After=network-online.target
Wants=network-online.target

[Service]
Type=forking
User=bitcoingold
Group=bitcoingold
ExecStart=/usr/local/bin/bgoldd -daemon -conf=/var/lib/bitcoingold/.bitcoingold/bitcoingold.conf
ExecStop=/usr/local/bin/bgold-cli -conf=/var/lib/bitcoingold/.bitcoingold/bitcoingold.conf stop
Restart=on-failure
RestartSec=30
TimeoutStartSec=infinity
TimeoutStopSec=600

# --- service hardening ---
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=full
ProtectHome=true
ReadWritePaths=/var/lib/bitcoingold/.bitcoingold

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now btgd.service

8. Firewall

Allow inbound P2P from anywhere (so the node can serve the network), keep RPC on localhost only.

sudo ufw allow 8338/tcp comment "Bitcoin Gold P2P"
sudo ufw status verbose

If you also run an Electrum server, Blockbook, or web dashboard on the same host, add the appropriate ports then.

Do not open 8332 to the network

Port 8332 is RPC. The rpcallowip line above restricts it to localhost, but a belt-and-braces ufw rule keeps you safe if you ever relax rpcallowip for a moment.

9. Wait for initial sync

Initial synchronization time depends on storage, CPU, memory, peer quality, and current chain size. Watch progress instead of relying on a fixed estimate:

sudo -u bitcoingold bgold-cli -conf=/var/lib/bitcoingold/.bitcoingold/bitcoingold.conf getblockchaininfo | jq '{headers, blocks, verificationprogress, size_on_disk}'

verificationprogress should approach 0.9999…. The chain is fully synced when blocks == headers.

While it syncs, you can use the time to set up a DNS seeder role or run Blockbook on top.

10. Verification

Once sync is complete, cross-check your view against the public network.

# Peers — should grow to ~20+ outbound + 100+ inbound
bgold-cli getnetworkinfo | jq '{connections: .connections, networks: [.networks[] | {name, reachable}]}'

# Tip block hash and height
bgold-cli getbestblockhash
bgold-cli getblockcount

# Compare against the public explorer
curl -s https://explorer.bitcoingold.services/api/v2/btg/info | jq '.data | {blocks, bestblockhash}'

# Sanity: get a block from your local node and check its hash
HASH=$(bgold-cli getblockhash 800000)
bgold-cli getblock "$HASH" | jq '{hash, confirmations, height, txcount: (.tx | length)}'

If getbestblockhash matches the explorer's bestblockhash for the same height, your node is in full consensus with the network.

11. Log rotation

debug.log can grow to several GB over months. Keep it under control with logrotate.

sudo tee /etc/logrotate.d/bitcoingold > /dev/null <<'EOF'
/var/log/bitcoingold.log {
    daily
    rotate 7
    compress
    missingok
    notifempty
    copytruncate
    sharedscripts
    postrotate
        # bgoldd reopens the log on SIGHUP; some setups need this:
        # pkill -HUP -f bgoldd
    endscript
}
EOF

12. Maintenance

Snapshots / backups

Wallet data is the only irreplaceable node data. Blocks, indexes, and chainstate can be downloaded or rebuilt. Back up bitcoingold.conf and the systemd unit so the service can be reconstructed. If you enable wallet functionality, use the wallet RPC backup procedure and keep encrypted, off-host copies; the reference configuration above uses disablewallet=1 and therefore has no wallet to back up.

Restarting safely

sudo systemctl restart btgd.service
sudo journalctl -u btgd.service -f

Always stop or restart through systemctl so the daemon can flush its databases cleanly. Do not use kill -9 except as a last resort.

Upgrading

  1. Read the release notes and identify the exact signed tag or reviewed commit to deploy.
  2. cd /usr/local/src/BTCGPU && git fetch --tags origin
  3. git checkout <reviewed-tag-or-commit> and rebuild using the same configure options as the installed version.
  4. sudo systemctl stop btgd.service && sudo make install
  5. sudo systemctl start btgd.service
  6. sudo journalctl -u btgd.service -f — confirm a clean startup and expected version.

Read the release notes before upgrading

Major version bumps (0.15 → 0.17) can change bitcoingold.conf defaults and deprecate RPCs. Always read the corresponding Release-Notes-vX.Y.Z.md from the wiki first.

Troubleshooting

Daemon won't start: "Unable to bind to 0.0.0.0:8338"

Another process is already using the port, or the configured bind address is not available on the host.

sudo ss -lntp | grep 8338

Daemon won't start: "Cannot obtain a lock on data directory"

Another bgoldd process may already be using the data directory. Do not delete the lock until you have confirmed that no daemon is running.

pgrep -a bgoldd
sudo systemctl status btgd.service

"RPC: connection refused" when using bgold-cli

You're probably running bgold-cli as root or as a different user than the daemon. Use sudo -u bitcoingold bgold-cli ... or add the same rpcuser/rpcpassword to ~/.bitcoingold/bitcoingold.conf for your local user.

"Pruning is not compatible with -txindex"

You can't have both. To enable txindex=1, leave pruning off (the default).

Chain stuck for hours at the same height

Check the DNS seeds you have configured. If dnsseed=0, there are no addnode entries, and the node has no usable cached peers, peer discovery may stall. Re-enable DNS seeds and confirm that both UDP and TCP DNS resolution work:

sudo ufw allow out 53/udp
sudo ufw allow out 53/tcp

Out of disk space

Disk requirements grow continuously and are substantially higher when txindex=1 is enabled. Measure the current data directory and retain generous free space for growth and database compaction.

df -h /var/lib/bitcoingold
du -sh /var/lib/bitcoingold/.bitcoingold/{blocks,chainstate,indexes}

What to do next