# 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.