proxmox/docs/README.md

# Project Documentation

**Last Updated:** 2025-01-20  
**Status:** Active Documentation

---

## 📚 Master Documentation Index

**👉 Start here:** **[MASTER_INDEX.md](MASTER_INDEX.md)** - Complete documentation index with all documents organized by category, priority, and cross-references.

---

## 🚀 Quick Navigation

### First Time Here?

1. **[01-getting-started/README_START_HERE.md](01-getting-started/README_START_HERE.md)** - Complete getting started guide
2. **[01-getting-started/PREREQUISITES.md](01-getting-started/PREREQUISITES.md)** - System requirements
3. **[MASTER_INDEX.md](MASTER_INDEX.md)** - Browse all documentation

### Common Tasks

| Task | Document |
|------|----------|
| **Deploy System** | [02-architecture/ORCHESTRATION_DEPLOYMENT_GUIDE.md](02-architecture/ORCHESTRATION_DEPLOYMENT_GUIDE.md) |
| **Configure Network** | [02-architecture/NETWORK_ARCHITECTURE.md](02-architecture/NETWORK_ARCHITECTURE.md) |
| **Troubleshoot Issues** | [09-troubleshooting/TROUBLESHOOTING_FAQ.md](09-troubleshooting/TROUBLESHOOTING_FAQ.md) |
| **Operational Procedures** | [03-deployment/OPERATIONAL_RUNBOOKS.md](03-deployment/OPERATIONAL_RUNBOOKS.md) |
| **Check Status** | [03-deployment/DEPLOYMENT_STATUS_CONSOLIDATED.md](03-deployment/DEPLOYMENT_STATUS_CONSOLIDATED.md) |

---

## 📁 Directory Structure

```
docs/
├── MASTER_INDEX.md                    # Complete documentation index
├── README.md                          # This file
│
├── 01-getting-started/                # Getting started guides
│   ├── README.md
│   ├── README_START_HERE.md
│   └── PREREQUISITES.md
│
├── 02-architecture/                   # Core architecture & design
│   ├── README.md
│   ├── NETWORK_ARCHITECTURE.md
│   ├── ORCHESTRATION_DEPLOYMENT_GUIDE.md
│   └── VMID_ALLOCATION_FINAL.md
│
├── 03-deployment/                     # Deployment & operations
│   ├── README.md
│   ├── OPERATIONAL_RUNBOOKS.md
│   ├── VALIDATED_SET_DEPLOYMENT_GUIDE.md
│   ├── DEPLOYMENT_STATUS_CONSOLIDATED.md
│   ├── DEPLOYMENT_READINESS.md
│   ├── RUN_DEPLOYMENT.md
│   └── REMOTE_DEPLOYMENT.md
│
├── 04-configuration/                  # Configuration & setup
│   ├── README.md
│   ├── MCP_SETUP.md
│   ├── ER605_ROUTER_CONFIGURATION.md
│   ├── CLOUDFLARE_ZERO_TRUST_GUIDE.md
│   ├── SECRETS_KEYS_CONFIGURATION.md
│   ├── ENV_STANDARDIZATION.md
│   ├── CREDENTIALS_CONFIGURED.md
│   ├── SSH_SETUP.md
│   └── finalize-token.md
│
├── 05-network/                        # Network infrastructure
│   ├── README.md
│   ├── NETWORK_STATUS.md
│   ├── NGINX_ARCHITECTURE_RPC.md
│   ├── CLOUDFLARE_NGINX_INTEGRATION.md
│   ├── RPC_NODE_TYPES_ARCHITECTURE.md
│   └── RPC_TEMPLATE_TYPES.md
│
├── 06-besu/                           # Besu & blockchain
│   ├── README.md
│   ├── BESU_ALLOWLIST_RUNBOOK.md
│   ├── BESU_ALLOWLIST_QUICK_START.md
│   ├── BESU_NODES_FILE_REFERENCE.md
│   ├── BESU_OFFICIAL_REFERENCE.md
│   ├── BESU_OFFICIAL_UPDATES.md
│   ├── QUORUM_GENESIS_TOOL_REVIEW.md
│   ├── VALIDATOR_KEY_DETAILS.md
│   └── COMPREHENSIVE_CONSISTENCY_REVIEW.md
│
├── 07-ccip/                           # CCIP & Chainlink
│   ├── README.md
│   └── CCIP_DEPLOYMENT_SPEC.md
│
├── 08-monitoring/                     # Monitoring & observability
│   ├── README.md
│   ├── MONITORING_SUMMARY.md
│   └── BLOCK_PRODUCTION_MONITORING.md
│
├── 09-troubleshooting/                # Troubleshooting
│   ├── README.md
│   ├── TROUBLESHOOTING_FAQ.md
│   └── QBFT_TROUBLESHOOTING.md
│
├── 10-best-practices/                 # Best practices
│   ├── README.md
│   ├── RECOMMENDATIONS_AND_SUGGESTIONS.md
│   ├── IMPLEMENTATION_CHECKLIST.md
│   ├── BEST_PRACTICES_SUMMARY.md
│   └── QUICK_WINS.md
│
├── 11-references/                     # Technical references
│   ├── README.md
│   ├── APT_PACKAGES_CHECKLIST.md
│   ├── PATHS_REFERENCE.md
│   ├── SCRIPT_REVIEW.md
│   └── TEMPLATE_BASE_WORKFLOW.md
│
├── 12-quick-reference/                # Quick references
│   ├── README.md
│   ├── QUICK_REFERENCE.md
│   ├── VALIDATED_SET_QUICK_REFERENCE.md
│   └── QUICK_START_TEMPLATE.md
│
└── archive/                            # Historical documents
    └── README.md
```

---

## 📖 Documentation Categories

### 🏗️ Core Architecture

Essential architecture and design documents:

- **[02-architecture/NETWORK_ARCHITECTURE.md](02-architecture/NETWORK_ARCHITECTURE.md)** - Complete network architecture (6×/28 blocks, VLANs, NAT pools)
- **[02-architecture/ORCHESTRATION_DEPLOYMENT_GUIDE.md](02-architecture/ORCHESTRATION_DEPLOYMENT_GUIDE.md)** - Enterprise deployment orchestration
- **[02-architecture/VMID_ALLOCATION_FINAL.md](02-architecture/VMID_ALLOCATION_FINAL.md)** - VMID allocation registry (11,000 VMIDs)
- **[07-ccip/CCIP_DEPLOYMENT_SPEC.md](07-ccip/CCIP_DEPLOYMENT_SPEC.md)** - CCIP fleet deployment specification

**See:** [02-architecture/README.md](02-architecture/README.md)

### 🚀 Deployment & Operations

Deployment guides and operational procedures:

- **[02-architecture/ORCHESTRATION_DEPLOYMENT_GUIDE.md](02-architecture/ORCHESTRATION_DEPLOYMENT_GUIDE.md)** - Complete deployment orchestration
- **[03-deployment/VALIDATED_SET_DEPLOYMENT_GUIDE.md](03-deployment/VALIDATED_SET_DEPLOYMENT_GUIDE.md)** - Validated set deployment
- **[03-deployment/OPERATIONAL_RUNBOOKS.md](03-deployment/OPERATIONAL_RUNBOOKS.md)** - All operational procedures
- **[03-deployment/DEPLOYMENT_STATUS_CONSOLIDATED.md](03-deployment/DEPLOYMENT_STATUS_CONSOLIDATED.md)** - Current deployment status

**See:** [03-deployment/README.md](03-deployment/README.md)

### ⚙️ Configuration & Setup

Setup and configuration guides:

- **[04-configuration/MCP_SETUP.md](04-configuration/MCP_SETUP.md)** - MCP Server configuration
- **[04-configuration/ENV_STANDARDIZATION.md](04-configuration/ENV_STANDARDIZATION.md)** - Environment variables
- **[04-configuration/SECRETS_KEYS_CONFIGURATION.md](04-configuration/SECRETS_KEYS_CONFIGURATION.md)** - Secrets and keys management
- **[04-configuration/ER605_ROUTER_CONFIGURATION.md](04-configuration/ER605_ROUTER_CONFIGURATION.md)** - Router configuration
- **[04-configuration/CLOUDFLARE_ZERO_TRUST_GUIDE.md](04-configuration/CLOUDFLARE_ZERO_TRUST_GUIDE.md)** - Cloudflare Zero Trust

**See:** [04-configuration/README.md](04-configuration/README.md)

### 🌐 Network Infrastructure

Network architecture and configuration:

- **[02-architecture/NETWORK_ARCHITECTURE.md](02-architecture/NETWORK_ARCHITECTURE.md)** - Complete network architecture
- **[04-configuration/ER605_ROUTER_CONFIGURATION.md](04-configuration/ER605_ROUTER_CONFIGURATION.md)** - Router configuration
- **[04-configuration/CLOUDFLARE_ZERO_TRUST_GUIDE.md](04-configuration/CLOUDFLARE_ZERO_TRUST_GUIDE.md)** - Cloudflare Zero Trust
- **[05-network/NGINX_ARCHITECTURE_RPC.md](05-network/NGINX_ARCHITECTURE_RPC.md)** - NGINX RPC architecture

**See:** [05-network/README.md](05-network/README.md)

### ⛓️ Besu & Blockchain

Besu configuration and operations:

- **[06-besu/BESU_ALLOWLIST_RUNBOOK.md](06-besu/BESU_ALLOWLIST_RUNBOOK.md)** - Allowlist management
- **[06-besu/BESU_ALLOWLIST_QUICK_START.md](06-besu/BESU_ALLOWLIST_QUICK_START.md)** - Quick start for allowlist
- **[06-besu/BESU_NODES_FILE_REFERENCE.md](06-besu/BESU_NODES_FILE_REFERENCE.md)** - Nodes file reference
- **[09-troubleshooting/QBFT_TROUBLESHOOTING.md](09-troubleshooting/QBFT_TROUBLESHOOTING.md)** - QBFT troubleshooting

**See:** [06-besu/README.md](06-besu/README.md)

### 🔗 CCIP & Chainlink

CCIP deployment and configuration:

- **[07-ccip/CCIP_DEPLOYMENT_SPEC.md](07-ccip/CCIP_DEPLOYMENT_SPEC.md)** - CCIP deployment specification
- **[05-network/RPC_TEMPLATE_TYPES.md](05-network/RPC_TEMPLATE_TYPES.md)** - RPC template types

**See:** [07-ccip/README.md](07-ccip/README.md)

### 📊 Monitoring & Observability

Monitoring setup and configuration:

- **[08-monitoring/MONITORING_SUMMARY.md](08-monitoring/MONITORING_SUMMARY.md)** - Monitoring setup
- **[08-monitoring/BLOCK_PRODUCTION_MONITORING.md](08-monitoring/BLOCK_PRODUCTION_MONITORING.md)** - Block production monitoring

**See:** [08-monitoring/README.md](08-monitoring/README.md)

### 🔧 Troubleshooting

Troubleshooting guides and FAQs:

- **[09-troubleshooting/TROUBLESHOOTING_FAQ.md](09-troubleshooting/TROUBLESHOOTING_FAQ.md)** - Common issues and solutions
- **[09-troubleshooting/QBFT_TROUBLESHOOTING.md](09-troubleshooting/QBFT_TROUBLESHOOTING.md)** - QBFT consensus troubleshooting
- **[06-besu/BESU_ALLOWLIST_QUICK_START.md](06-besu/BESU_ALLOWLIST_QUICK_START.md)** - Allowlist troubleshooting

**See:** [09-troubleshooting/README.md](09-troubleshooting/README.md)

### ✅ Best Practices

Best practices and recommendations:

- **[10-best-practices/RECOMMENDATIONS_AND_SUGGESTIONS.md](10-best-practices/RECOMMENDATIONS_AND_SUGGESTIONS.md)** - Comprehensive recommendations
- **[10-best-practices/IMPLEMENTATION_CHECKLIST.md](10-best-practices/IMPLEMENTATION_CHECKLIST.md)** - Implementation checklist
- **[10-best-practices/BEST_PRACTICES_SUMMARY.md](10-best-practices/BEST_PRACTICES_SUMMARY.md)** - Best practices summary

**See:** [10-best-practices/README.md](10-best-practices/README.md)

---

## 📋 Quick Reference

### Essential Documents

| Document | When to Use |
|----------|-------------|
| **[MASTER_INDEX.md](MASTER_INDEX.md)** | Browse all documentation |
| **[02-architecture/ORCHESTRATION_DEPLOYMENT_GUIDE.md](02-architecture/ORCHESTRATION_DEPLOYMENT_GUIDE.md)** | Deploy the system |
| **[02-architecture/NETWORK_ARCHITECTURE.md](02-architecture/NETWORK_ARCHITECTURE.md)** | Understand network design |
| **[03-deployment/OPERATIONAL_RUNBOOKS.md](03-deployment/OPERATIONAL_RUNBOOKS.md)** | Run operations |
| **[09-troubleshooting/TROUBLESHOOTING_FAQ.md](09-troubleshooting/TROUBLESHOOTING_FAQ.md)** | Solve problems |

### Quick Reference Guides

- **[12-quick-reference/QUICK_REFERENCE.md](12-quick-reference/QUICK_REFERENCE.md)** - ProxmoxVE scripts quick reference
- **[12-quick-reference/VALIDATED_SET_QUICK_REFERENCE.md](12-quick-reference/VALIDATED_SET_QUICK_REFERENCE.md)** - Validated set quick reference
- **[12-quick-reference/QUICK_START_TEMPLATE.md](12-quick-reference/QUICK_START_TEMPLATE.md)** - Quick start template

---

## 🔗 Related Documentation

### Project Documentation

- **[../README.md](../README.md)** - Main project README
- **[../PROJECT_STRUCTURE.md](../PROJECT_STRUCTURE.md)** - Project structure

### Submodule Documentation

- **[../mcp-proxmox/README.md](../mcp-proxmox/README.md)** - MCP Server documentation
- **[../ProxmoxVE/README.md](../ProxmoxVE/README.md)** - ProxmoxVE scripts documentation
- **[../smom-dbis-138-proxmox/README.md](../smom-dbis-138-proxmox/README.md)** - Deployment scripts documentation

---

## 📊 Documentation Statistics

- **Total Active Documents:** 48 (organized in 12 directories)
- **Archived Documents:** 75+
- **Core Architecture:** 3 documents
- **Deployment Guides:** 6 documents
- **Troubleshooting Guides:** 2 documents
- **Best Practices:** 4 documents

---

## 📝 Document Maintenance

### Update Frequency

- **Critical Documents:** Updated weekly or as changes occur
- **Reference Documents:** Updated monthly or as needed
- **Historical Documents:** Archived, not updated

### Review Cycle

- **Quarterly:** Architecture and design documents
- **Monthly:** Operational runbooks
- **As Needed:** Troubleshooting and quick references

---

## 🆘 Getting Help

### Common Questions

1. **Where do I start?** → [01-getting-started/README_START_HERE.md](01-getting-started/README_START_HERE.md)
2. **How do I deploy?** → [02-architecture/ORCHESTRATION_DEPLOYMENT_GUIDE.md](02-architecture/ORCHESTRATION_DEPLOYMENT_GUIDE.md)
3. **What's the network architecture?** → [02-architecture/NETWORK_ARCHITECTURE.md](02-architecture/NETWORK_ARCHITECTURE.md)
4. **I have a problem** → [09-troubleshooting/TROUBLESHOOTING_FAQ.md](09-troubleshooting/TROUBLESHOOTING_FAQ.md)
5. **What operations can I run?** → [03-deployment/OPERATIONAL_RUNBOOKS.md](03-deployment/OPERATIONAL_RUNBOOKS.md)

### Support Resources

- **[09-troubleshooting/TROUBLESHOOTING_FAQ.md](09-troubleshooting/TROUBLESHOOTING_FAQ.md)** - Common issues and solutions
- **[03-deployment/OPERATIONAL_RUNBOOKS.md](03-deployment/OPERATIONAL_RUNBOOKS.md)** - Operational procedures
- **[MASTER_INDEX.md](MASTER_INDEX.md)** - Complete documentation index

---

## 📅 Recent Updates

- **2025-01-20:** Complete documentation consolidation and upgrade
- **2025-01-20:** Network architecture upgraded to v2.0
- **2025-01-20:** Orchestration deployment guide created
- **2025-01-20:** 75+ documents archived, organized structure
- **2025-01-20:** Directory structure created with 12 organized categories

---

**Last Updated:** 2025-01-20  
**Maintained By:** Infrastructure Team  
**Review Cycle:** Monthly