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)

# 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

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

# 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

# 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

# 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	System design, data flow, component interactions
Features	Detailed feature specifications
Roadmap	Development phases and milestones
API Reference	REST API and gRPC specifications
Deployment	Production deployment guides

📄 License

NxMesh is licensed under the Apache License 3.0. See LICENSE for details.

---