Guts Operator Guide

Comprehensive documentation for deploying, operating, and maintaining Guts nodes in production environments.

Overview

This guide is designed for operators who need to run Guts nodes reliably in production. Whether you're running a single node for development, a validator in the consensus network, or a fleet of nodes serving a large organization, this documentation covers everything you need to know.

Quick Navigation

Section	Description	Audience
Quickstart	Deploy a node in 5 minutes	New operators
Requirements	Hardware, software, network requirements	All operators
Architecture	System architecture overview	All operators
Installation	Detailed installation guides	All operators
Configuration	Configuration reference	All operators
Operations	Day-to-day operations	Production operators
Runbooks	Incident response procedures	On-call engineers
Troubleshooting	Common issues and solutions	All operators
Reference	CLI, API, and metrics reference	Advanced operators

Deployment Options

By Environment

Environment	Recommended Method	Guide
Development	Docker Compose	Docker Guide
Staging	Kubernetes	Kubernetes Guide
Production	Kubernetes + Helm	Kubernetes Guide
Bare Metal	Systemd	Bare Metal Guide

By Cloud Provider

Provider	Guide	Terraform
AWS	AWS Quickstart	✅ Available
GCP	GCP Quickstart	✅ Available
Azure	Azure Quickstart	✅ Available
Multi-Cloud	Federation Guide	✅ Available

Node Types

Guts supports different node configurations depending on your use case:

Full Node

A full node stores all repository data and participates in P2P replication but does not participate in consensus.

# Start a full node
guts-node --api-addr 0.0.0.0:8080 --p2p-addr 0.0.0.0:9000

Use cases:

• API gateway for applications
• Read replicas for load distribution
• Local development and testing

Validator Node

A validator node participates in Simplex BFT consensus, proposing and voting on blocks.

# Start a validator node
guts-node \
  --api-addr 0.0.0.0:8080 \
  --p2p-addr 0.0.0.0:9000 \
  --private-key <hex-encoded-key> \
  --consensus-enabled \
  --consensus-use-simplex-bft \
  --genesis-file genesis.json

Requirements:

• Stable network connectivity (99.9%+ uptime)
• High-performance hardware (see Requirements)
• Secure key management
• 24/7 monitoring

Key Concepts

Simplex BFT Consensus

Guts uses Simplex BFT (Byzantine Fault Tolerant) consensus for total ordering of all state changes. The consensus engine:

• Tolerates up to f < n/3 Byzantine (malicious) validators
• Achieves finality in 3 network hops
• Produces blocks at configurable intervals (default: 2 seconds)

P2P Networking

All Guts nodes communicate via encrypted P2P connections using the commonware networking stack:

• Transport: QUIC (UDP) and TCP
• Encryption: Noise protocol with Ed25519 keys
• Discovery: Bootstrap nodes + peer exchange

Content-Addressed Storage

Git objects are stored using content-addressed storage, enabling:

• Automatic deduplication
• Integrity verification via SHA-1/SHA-256
• Efficient P2P replication

Operational Lifecycle

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Deploy    │────▶│   Operate   │────▶│   Upgrade   │
└─────────────┘     └─────────────┘     └─────────────┘
       │                   │                   │
       ▼                   ▼                   ▼
  Installation         Monitoring          Zero-Downtime
  Configuration        Alerting            Rolling Updates
  Verification         Backup              Rollback

1. Deploy

• Choose deployment method based on environment
• Configure node identity and networking
• Verify connectivity and sync status

2. Operate

• Monitor metrics and logs
• Respond to alerts using runbooks
• Perform regular backups
• Apply security patches

3. Upgrade

• Review release notes and compatibility
• Test in staging environment
• Perform zero-downtime upgrade
• Verify functionality and rollback if needed

Support Channels

Channel	Purpose	Response Time
GitHub Issues	Bug reports, feature requests	1-3 days
Discord	Community support	Best effort
Documentation	Self-service guides	Instant

Version Compatibility

Node Version	Protocol Version	Network Compatibility
1.0.x	1	mainnet, testnet
0.x.x	0	devnet only

Security Considerations

• Key Management: Never expose private keys in logs or environment variables visible to unauthorized users
• Network Security: Always use TLS for external API access
• Access Control: Restrict metrics and admin endpoints to internal networks
• Updates: Subscribe to security advisories and apply patches promptly

See Security Hardening for detailed recommendations.

Contributing to Documentation

Found an error or want to improve this documentation? Contributions are welcome!

1. Fork the repository
2. Edit files in docs/operator/
3. Submit a pull request

Next Steps

1. New operators: Start with Quickstart
2. Production deployment: Read Requirements then choose an Installation method
3. Existing operators: Review Operations and Runbooks