Initial commit: TRI bootstrap server

- Caddy HTTPS static file server config - Tor hidden service (V3 onion) for anonymous access - Bootstrap generation script (blk0001.dat + txleveldb + database) - Dropbox upload script - Systemd services (tor-bootstrap, caddy) - Operator guide and verification script
2026-04-21 01:53:34 -07:00
commit 50bd396c2b
11 changed files with 819 additions and 0 deletions
@@ -0,0 +1,129 @@
+# 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:
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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:
+```bash
+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.