Add project structure and roadmap documentation
- Created `project-structure.md` to outline the directory layout, crate dependencies, design principles, module guidelines, and naming conventions for the NxMesh codebase. - Introduced `roadmap.md` detailing the development phases, milestones, tasks, deliverables, and resource requirements for the NxMesh project, spanning from foundational setup to enterprise features.
This commit is contained in:
GW_MC
202
README.md
202
README.md
@@ -1,2 +1,202 @@
|
||||
# NxMesh
|
||||
# NxMesh - Distributed Nginx Management System
|
||||
|
||||
> **NxMesh** is a modern, scalable, distributed system for managing nginx instances across diverse infrastructure environments. Built with a master-agent architecture inspired by service mesh patterns, NxMesh provides centralized control with local intelligence.
|
||||
|
||||
## 🎯 Project Vision
|
||||
|
||||
NxMesh transforms nginx from a standalone reverse proxy into a **distributed, programmable edge layer**. By adopting a control plane (master) + data plane (agent/sidecar) architecture, NxMesh enables:
|
||||
|
||||
- **Centralized Management**: Control thousands of nginx instances from a single control plane
|
||||
- **Dynamic Configuration**: Real-time configuration updates without restarts or connection drops
|
||||
- **Observability**: Unified metrics, logs, and health status across the entire fleet
|
||||
- **Hybrid Deployment**: Support for Docker, Kubernetes, VMs, and bare metal environments
|
||||
- **High Availability**: Fault-tolerant design with automatic failover and recovery
|
||||
|
||||
## 🏗️ Architecture Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ CONTROL PLANE (Master) │
|
||||
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ NxMesh Master │ │
|
||||
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
|
||||
│ │ │ API │ │ Config │ │ Cluster │ │ Admin │ │ │
|
||||
│ │ │ Server │ │ Manager │ │ Coordinator │ │ Console │ │ │
|
||||
│ │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │
|
||||
│ │ └──────────────────┴──────────────────┴──────────────────┘ │ │
|
||||
│ │ │ │ │
|
||||
│ │ PostgreSQL (State) │ │
|
||||
│ └──────────────────────────────┼─────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ gRPC/TLS │ WebSocket (Events) │
|
||||
│ ▼ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌───────────────────────────┼───────────────────────────┐
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
|
||||
│ AGENT 1 │ │ AGENT 2 │ │ AGENT N │
|
||||
│ (Sidecar) │ │ (Standalone) │ │ (K8s Pod) │
|
||||
│ ┌───────────┐ │ │ ┌───────────┐ │ │ ┌───────────┐ │
|
||||
│ │ NxMesh │ │ │ │ NxMesh │ │ │ │ NxMesh │ │
|
||||
│ │ Agent │ │ │ │ Agent │ │ │ │ Agent │ │
|
||||
│ └─────┬─────┘ │ │ └─────┬─────┘ │ │ └─────┬─────┘ │
|
||||
│ │ │ │ │ │ │ │ │
|
||||
│ ┌────┴────┐ │ │ ┌────┴────┐ │ │ ┌────┴────┐ │
|
||||
│ │ Nginx │ │ │ │ Nginx │ │ │ │ Nginx │ │
|
||||
│ │ Instance│ │ │ │ Instance│ │ │ │ Instance│ │
|
||||
│ └─────────┘ │ │ └─────────┘ │ │ └─────────┘ │
|
||||
└───────────────┘ └───────────────┘ └───────────────┘
|
||||
Docker Compose VM/Bare Metal Kubernetes
|
||||
```
|
||||
|
||||
### Core Components
|
||||
|
||||
| Component | Description | Technology |
|
||||
|-----------|-------------|------------|
|
||||
| **Master** | Central control plane - API, embedded Web UI, config distribution | Rust (Axum/gRPC) + Embedded Vite React |
|
||||
| **Agent** | Local nginx controller - configuration, health checks, metrics | Rust (Tokio) |
|
||||
| **Database** | Persistent state storage | PostgreSQL |
|
||||
|
||||
## 🚀 Key Features
|
||||
|
||||
### Phase 1: Foundation
|
||||
- [ ] **Master Control Plane**
|
||||
- RESTful API for configuration management
|
||||
- gRPC for agent communication
|
||||
- PostgreSQL persistence
|
||||
- JWT-based authentication
|
||||
|
||||
- [ ] **Agent Sidecar**
|
||||
- Docker deployment mode (sidecar pattern)
|
||||
- Standalone deployment mode
|
||||
- Automatic nginx lifecycle management
|
||||
- Configuration hot-reloading
|
||||
|
||||
- [ ] **Configuration Management**
|
||||
- Virtual host (server block) templating
|
||||
- Upstream pool management
|
||||
- SSL/TLS certificate management
|
||||
- Configuration versioning & rollback
|
||||
|
||||
### Phase 2: Resilience
|
||||
- [ ] **High Availability**
|
||||
- Master clustering with Raft consensus
|
||||
- Agent auto-reconnection with exponential backoff
|
||||
- Configuration drift detection & auto-healing
|
||||
|
||||
- [ ] **Observability**
|
||||
- Real-time metrics collection (Prometheus)
|
||||
- Structured logging (OpenTelemetry)
|
||||
- Health check dashboards
|
||||
- Alert management
|
||||
|
||||
### Phase 3: Advanced
|
||||
- [ ] **Traffic Management**
|
||||
- Dynamic load balancing strategies
|
||||
- Circuit breaker patterns
|
||||
- Rate limiting & WAF rules
|
||||
- A/B testing & canary deployments
|
||||
|
||||
- [ ] **Multi-tenancy**
|
||||
- Organization/workspace isolation
|
||||
- RBAC (Role-Based Access Control)
|
||||
- Resource quotas & limits
|
||||
|
||||
## 📦 Deployment Modes
|
||||
|
||||
### 1. Docker Sidecar (Recommended for Development)
|
||||
```yaml
|
||||
# docker-compose.yml
|
||||
services:
|
||||
nginx:
|
||||
image: nginx:alpine
|
||||
|
||||
nxmesh-agent:
|
||||
image: nxmesh/agent:latest
|
||||
environment:
|
||||
- NXMESH_MASTER_URL=wss://master.nxmesh.io:8443
|
||||
- NXMESH_AGENT_TOKEN=${AGENT_TOKEN}
|
||||
network_mode: service:nginx # Share network namespace
|
||||
pid: service:nginx # Share PID namespace (for nginx reload)
|
||||
```
|
||||
|
||||
### 2. Kubernetes Sidecar
|
||||
```yaml
|
||||
# deployment.yaml
|
||||
spec:
|
||||
containers:
|
||||
- name: nginx
|
||||
image: nginx:alpine
|
||||
- name: nxmesh-agent
|
||||
image: nxmesh/agent:latest
|
||||
env:
|
||||
- name: NXMESH_MASTER_URL
|
||||
value: "wss://master.nxmesh.svc:8443"
|
||||
```
|
||||
|
||||
### 3. Standalone (VM/Bare Metal)
|
||||
```bash
|
||||
# Install agent
|
||||
curl -fsSL https://get.nxmesh.io | bash
|
||||
|
||||
# Configure and start
|
||||
nxmesh-agent --master-url wss://master.nxmesh.io:8443 --token ${AGENT_TOKEN}
|
||||
```
|
||||
|
||||
## 📋 Quick Start
|
||||
|
||||
### Prerequisites
|
||||
- Docker & Docker Compose
|
||||
- Rust 1.75+ (for development)
|
||||
- PostgreSQL 16+
|
||||
|
||||
### Development Setup
|
||||
```bash
|
||||
# Clone and setup
|
||||
git clone https://github.com/your-org/nxmesh.git
|
||||
cd nxmesh
|
||||
just setup
|
||||
|
||||
# Start development environment
|
||||
just dev
|
||||
|
||||
# Access services
|
||||
# - Web UI: http://localhost:3000
|
||||
# - API: http://localhost:8080
|
||||
# - Nginx: http://localhost:80
|
||||
```
|
||||
|
||||
### Production Deployment
|
||||
```bash
|
||||
# Deploy master
|
||||
docker run -d \
|
||||
-p 8080:8080 \
|
||||
-p 8443:8443 \
|
||||
-e DATABASE_URL=postgres://... \
|
||||
nxmesh/master:latest
|
||||
|
||||
# Deploy agent (on nginx host)
|
||||
docker run -d \
|
||||
--network container:nginx \
|
||||
-e NXMESH_MASTER_URL=wss://master.example.com:8443 \
|
||||
-e NXMESH_AGENT_TOKEN=<token> \
|
||||
nxmesh/agent:latest
|
||||
```
|
||||
|
||||
## 📚 Documentation
|
||||
|
||||
| Document | Description |
|
||||
|----------|-------------|
|
||||
| [Architecture](./docs/architecture.md) | System design, data flow, component interactions |
|
||||
| [Features](./docs/features.md) | Detailed feature specifications |
|
||||
| [Roadmap](./docs/roadmap.md) | Development phases and milestones |
|
||||
| [API Reference](./docs/api.md) | REST API and gRPC specifications |
|
||||
| [Deployment](./docs/deployment.md) | Production deployment guides |
|
||||
|
||||
## 📄 License
|
||||
|
||||
NxMesh is licensed under the Apache License 3.0. See [LICENSE](./LICENSE) for details.
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user