tri-bootstrap-server/docs/operator-guide.md

Operator Guide — Running a TRI Bootstrap Server

This guide covers everything a node operator needs to know to run a TRI bootstrap server in production.

Overview

The bootstrap server serves blockchain snapshot files to new TRI nodes that need to sync quickly without downloading from the peer-to-peer network. It is not a full node itself — it is a simple static file server.

When to Update the Bootstrap

Update the bootstrap when:

• A significant chain fork has been resolved
• A new TRI release includes consensus changes
• The existing bootstrap is causing nodes to land on the wrong chain

Step-by-Step: Updating the Bootstrap

1. Generate the Bootstrap on a Trusted Node

On a node that is fully synced and on the canonical chain:

# Get current block info first
./triangles-cli getblockcount
./triangles-cli getbestblockhash

# Generate the bootstrap (from the TRI Bootstrap Server repo)
./scripts/generate-bootstrap.sh ~/.triangles

# Review the output:
#   Block height: XXXXXX
#   Best block hash: XXXXXXXX...
#   SHA256: XXXXXXXX...

Compare the best block hash against:

• Another trusted synced node: ./triangles-cli -rpcconnect=OTHER_IP getbestblockhash
• The community Discord/Telegram if available
• Block explorers

Only proceed if the hash matches a known-good reference.

2. Transfer to the Server

# Direct upload (if you have SSH access)
scp triangles-bootstrap-YYYY-MM-DD.tar.gz user@your-server:/var/www/triangles-bootstrap/

# Or via Dropbox bridge:
./scripts/publish-bootstrap.sh triangles-bootstrap-YYYY-MM-DD.tar.gz

3. Install on the Server

# On the bootstrap server:
cd /var/www/triangles-bootstrap

# Create a DATED archive (for record-keeping)
cp triangles-bootstrap-YYYY-MM-DD.tar.gz triangles-bootstrap-YYYY-MM-DD.tar.gz.backup

# Update the symlink (so the canonical URL always serves latest)
ln -sf triangles-bootstrap-YYYY-MM-DD.tar.gz triangles-bootstrap.tar.gz

# Verify
sha256sum triangles-bootstrap.tar.gz
# Should match what you generated locally

4. Announce

Notify node operators of the new bootstrap URL and block height/hash so they can update their nodes.

Monitoring

Check the Server is Responding

# HTTPS
curl -I https://bootstrap.your-domain.com/triangles-bootstrap.tar.gz

# Should return: HTTP/2 200
# Content-Length: XXXXXXXX
# Content-Type: application/octet-stream

Check the Tor Onion

# Get your onion address
cat /var/lib/tor/tri-bootstrap/hostname

# Test it (from a machine with Tor installed)
torify curl -I http://your-onion-address.onion/triangles-bootstrap.tar.gz

Log Analysis

Check access logs:

tail -f /var/log/tri-bootstrap/access.log

Troubleshooting

Curl returns 404

• The archive file doesn't exist in the expected directory
• Check the Caddyfile root directive

TLS certificate errors

• Caddy might need to reload after DNS change
• Run: systemctl reload caddy

Tor onion not responding

• Check Tor is running: systemctl status tor@tri-bootstrap
• Check logs: journalctl -u tor@tri-bootstrap
• Verify hostname: cat /var/lib/tor/tri-bootstrap/hostname

Bootstrap still serving old chain

• A node downloaded the old archive before you updated
• Node operators need to delete their local chain state and re-download

Security Considerations

1. Wallet safety: Never include wallet files in the bootstrap archive. The generate script explicitly excludes wallet.dat*.
2. Only serve from trusted nodes: Generate bootstrap from a known-good synced node.
3. Verify hashes: Always cross-check the bestblockhash against other trusted references.
4. No authentication: The bootstrap server serves public files with no auth. This is intentional — any node should be able to download.
5. Tor anonymity: Using the Tor hidden service provides anonymity for nodes that need it, but is not required for clearnet users.