init
This commit is contained in:
Constantin
@@ -0,0 +1,462 @@
|
||||
|
||||
# Personal Internet Cell
|
||||
|
||||
## 🌟 Overview
|
||||
|
||||
The Personal Internet Cell is a **production-grade, self-hosted, decentralized digital infrastructure** that empowers you to:
|
||||
|
||||
- **Host your own services**: Email, calendar, contacts, files, DNS, DHCP, NTP
|
||||
- **Secure mesh networking**: Connect with trusted peers via WireGuard VPN
|
||||
- **Advanced routing**: VPN gateway, NAT, firewall, exit nodes, and bridge routing
|
||||
- **Enterprise security**: Self-hosted CA, certificate management, trust systems
|
||||
- **Modern management**: RESTful API, enhanced CLI, and comprehensive monitoring
|
||||
- **Event-driven architecture**: Service orchestration and real-time communication
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Key Features
|
||||
|
||||
### 🔧 **Core Services**
|
||||
- **Network Services**: DNS, DHCP, NTP with dynamic management
|
||||
- **VPN & Mesh**: WireGuard-based peer federation with dynamic IP updates
|
||||
- **Digital Services**: Email (SMTP/IMAP), Calendar/Contacts (CalDAV/CardDAV), File Storage (WebDAV)
|
||||
- **Security**: Self-hosted Certificate Authority, Age/Fernet encryption, trust management
|
||||
- **Container Orchestration**: Docker-based service management and deployment
|
||||
|
||||
### 🏗️ **Architecture Highlights**
|
||||
- **BaseServiceManager**: Unified interface across all 10 service managers
|
||||
- **Event-Driven Service Bus**: Real-time service communication and orchestration
|
||||
- **Centralized Configuration**: Type-safe validation, backup/restore, import/export
|
||||
- **Comprehensive Logging**: Structured JSON logs with rotation, search, and export
|
||||
- **Enhanced CLI**: Interactive mode, batch operations, service wizards
|
||||
- **Health Monitoring**: Real-time health checks and performance metrics
|
||||
|
||||
### 📊 **Production Features**
|
||||
- **Service Orchestration**: Automatic service dependency management
|
||||
- **Configuration Management**: Schema validation, versioning, and migration
|
||||
- **Error Handling**: Standardized error handling and recovery mechanisms
|
||||
- **Testing**: Comprehensive test suite with 77%+ coverage
|
||||
- **Documentation**: Complete API documentation and usage guides
|
||||
|
||||
---
|
||||
|
||||
## 📋 Table of Contents
|
||||
|
||||
1. [Quick Start](#quick-start)
|
||||
2. [Architecture](#architecture)
|
||||
3. [Service Managers](#service-managers)
|
||||
4. [API Reference](#api-reference)
|
||||
5. [CLI Guide](#cli-guide)
|
||||
6. [Configuration](#configuration)
|
||||
7. [Security](#security)
|
||||
8. [Development](#development)
|
||||
9. [Testing](#testing)
|
||||
10. [Deployment](#deployment)
|
||||
11. [Contributing](#contributing)
|
||||
12. [License](#license)
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- **Docker & Docker Compose** (recommended)
|
||||
- **Python 3.10+** (for CLI and development)
|
||||
- **2GB+ RAM, 10GB+ disk space**
|
||||
- **Ports**: 53, 80, 443, 3000, 51820
|
||||
|
||||
### 1. Clone and Setup
|
||||
|
||||
```bash
|
||||
git clone https://github.com/yourusername/PersonalInternetCell.git
|
||||
cd PersonalInternetCell
|
||||
|
||||
# Start with Docker (Recommended)
|
||||
docker-compose up --build
|
||||
|
||||
# Or run locally
|
||||
pip install -r api/requirements.txt
|
||||
python api/app.py
|
||||
```
|
||||
|
||||
### 2. Access Services
|
||||
|
||||
- **API**: http://localhost:3000
|
||||
- **Health Check**: http://localhost:3000/health
|
||||
- **Service Status**: http://localhost:3000/api/services/status
|
||||
|
||||
### 3. Use the Enhanced CLI
|
||||
|
||||
```bash
|
||||
# Show cell status
|
||||
python api/enhanced_cli.py --status
|
||||
|
||||
# Interactive mode
|
||||
python api/enhanced_cli.py --interactive
|
||||
|
||||
# Show all services
|
||||
python api/enhanced_cli.py --services
|
||||
|
||||
# Configuration wizard
|
||||
python api/enhanced_cli.py --wizard network
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Architecture
|
||||
|
||||
### **Service Manager Architecture**
|
||||
|
||||
All services inherit from `BaseServiceManager`, providing:
|
||||
- **Unified Interface**: Consistent methods across all services
|
||||
- **Health Monitoring**: Standardized health checks and metrics
|
||||
- **Error Handling**: Centralized error handling and logging
|
||||
- **Configuration**: Common configuration management patterns
|
||||
|
||||
### **Event-Driven Service Bus**
|
||||
|
||||
```python
|
||||
# Services communicate via events
|
||||
service_bus.register_service('network', network_manager)
|
||||
service_bus.register_service('wireguard', wireguard_manager)
|
||||
service_bus.publish_event(EventType.SERVICE_STARTED, 'network', data)
|
||||
```
|
||||
|
||||
### **Service Dependencies**
|
||||
|
||||
```
|
||||
wireguard → network
|
||||
email → network, vault
|
||||
calendar → network, vault
|
||||
files → network, vault
|
||||
routing → network, wireguard
|
||||
vault → network
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Service Managers
|
||||
|
||||
### **Core Network Services**
|
||||
- **NetworkManager**: DNS, DHCP, NTP with dynamic zone management
|
||||
- **WireGuardManager**: VPN configuration, peer management, key generation
|
||||
- **PeerRegistry**: Peer registration, IP updates, trust management
|
||||
|
||||
### **Digital Services**
|
||||
- **EmailManager**: SMTP/IMAP email with user management
|
||||
- **CalendarManager**: CalDAV/CardDAV calendar and contacts
|
||||
- **FileManager**: WebDAV file storage with user directories
|
||||
|
||||
### **Infrastructure Services**
|
||||
- **RoutingManager**: NAT, firewall, advanced routing (exit/bridge/split)
|
||||
- **VaultManager**: Certificate authority, trust management, encryption
|
||||
- **ContainerManager**: Docker orchestration and container management
|
||||
- **CellManager**: Overall cell configuration and service orchestration
|
||||
|
||||
---
|
||||
|
||||
## 📡 API Reference
|
||||
|
||||
### **Core Endpoints**
|
||||
|
||||
```bash
|
||||
# Service Status
|
||||
GET /api/services/status
|
||||
GET /api/services/connectivity
|
||||
|
||||
# Configuration Management
|
||||
GET /api/config
|
||||
PUT /api/config
|
||||
POST /api/config/backup
|
||||
POST /api/config/restore/<backup_id>
|
||||
|
||||
# Service Bus
|
||||
GET /api/services/bus/status
|
||||
GET /api/services/bus/events
|
||||
POST /api/services/bus/services/<service>/start
|
||||
|
||||
# Logging
|
||||
GET /api/logs/services/<service>
|
||||
POST /api/logs/search
|
||||
POST /api/logs/export
|
||||
```
|
||||
|
||||
### **Service-Specific Endpoints**
|
||||
|
||||
```bash
|
||||
# Network Services
|
||||
GET /api/dns/records
|
||||
POST /api/dns/records
|
||||
GET /api/dhcp/leases
|
||||
GET /api/ntp/status
|
||||
|
||||
# WireGuard & Peers
|
||||
GET /api/wireguard/peers
|
||||
POST /api/wireguard/peers
|
||||
GET /api/wireguard/status
|
||||
|
||||
# Digital Services
|
||||
GET /api/email/users
|
||||
GET /api/calendar/users
|
||||
GET /api/files/users
|
||||
|
||||
# Routing & Security
|
||||
GET /api/routing/status
|
||||
POST /api/routing/nat
|
||||
GET /api/vault/certificates
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💻 CLI Guide
|
||||
|
||||
### **Enhanced CLI Features**
|
||||
|
||||
```bash
|
||||
# Interactive Mode
|
||||
python api/enhanced_cli.py --interactive
|
||||
|
||||
# Batch Operations
|
||||
python api/enhanced_cli.py --batch "status" "services" "health"
|
||||
|
||||
# Configuration Management
|
||||
python api/enhanced_cli.py --export-config json
|
||||
python api/enhanced_cli.py --import-config config.json
|
||||
|
||||
# Service Wizards
|
||||
python api/enhanced_cli.py --wizard network
|
||||
python api/enhanced_cli.py --wizard email
|
||||
|
||||
# Health Monitoring
|
||||
python api/enhanced_cli.py --health
|
||||
python api/enhanced_cli.py --logs network
|
||||
```
|
||||
|
||||
### **Service Management**
|
||||
|
||||
```bash
|
||||
# Show status
|
||||
python api/enhanced_cli.py --status
|
||||
|
||||
# List services
|
||||
python api/enhanced_cli.py --services
|
||||
|
||||
# Peer management
|
||||
python api/enhanced_cli.py --peers
|
||||
|
||||
# Service logs
|
||||
python api/enhanced_cli.py --logs wireguard
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Configuration
|
||||
|
||||
### **Configuration Management**
|
||||
|
||||
```bash
|
||||
# Export configuration
|
||||
curl -X GET http://localhost:3000/api/config
|
||||
|
||||
# Update configuration
|
||||
curl -X PUT http://localhost:3000/api/config \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"cell_name": "mycell", "domain": "mycell.cell"}'
|
||||
|
||||
# Backup configuration
|
||||
curl -X POST http://localhost:3000/api/config/backup
|
||||
```
|
||||
|
||||
### **Service Configuration**
|
||||
|
||||
Each service has its own configuration schema:
|
||||
- **Network**: DNS zones, DHCP ranges, NTP servers
|
||||
- **WireGuard**: Interface settings, peer configurations
|
||||
- **Email**: Domain settings, user accounts, mailboxes
|
||||
- **Calendar**: User accounts, calendar sharing
|
||||
- **Files**: Storage quotas, user directories
|
||||
- **Routing**: NAT rules, firewall policies, routing tables
|
||||
|
||||
---
|
||||
|
||||
## 🔒 Security
|
||||
|
||||
### **Certificate Management**
|
||||
- **Self-hosted CA**: Issue and manage TLS certificates
|
||||
- **Certificate Lifecycle**: Generate, renew, revoke certificates
|
||||
- **Trust Management**: Direct and indirect trust relationships
|
||||
- **Age Encryption**: Modern encryption for sensitive data
|
||||
|
||||
### **Network Security**
|
||||
- **WireGuard VPN**: Secure peer-to-peer communication
|
||||
- **Firewall & NAT**: Granular access control
|
||||
- **Service Isolation**: Docker containers for each service
|
||||
- **Input Validation**: All API endpoints validate input
|
||||
|
||||
### **Data Protection**
|
||||
- **Encrypted Storage**: Sensitive data encrypted at rest
|
||||
- **Secure Communication**: TLS for all API endpoints
|
||||
- **Access Control**: Role-based access for services
|
||||
- **Audit Logging**: Comprehensive security event logging
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Development
|
||||
|
||||
### **Project Structure**
|
||||
|
||||
```
|
||||
PersonalInternetCell/
|
||||
├── api/ # Backend API server
|
||||
│ ├── base_service_manager.py # Base class for all services
|
||||
│ ├── config_manager.py # Configuration management
|
||||
│ ├── service_bus.py # Event-driven service bus
|
||||
│ ├── log_manager.py # Comprehensive logging
|
||||
│ ├── enhanced_cli.py # Enhanced CLI tool
|
||||
│ ├── network_manager.py # DNS, DHCP, NTP
|
||||
│ ├── wireguard_manager.py # VPN and peer management
|
||||
│ ├── email_manager.py # Email services
|
||||
│ ├── calendar_manager.py # Calendar services
|
||||
│ ├── file_manager.py # File storage
|
||||
│ ├── routing_manager.py # Routing and NAT
|
||||
│ ├── vault_manager.py # Security and trust
|
||||
│ ├── container_manager.py # Container orchestration
|
||||
│ ├── cell_manager.py # Overall cell management
|
||||
│ ├── peer_registry.py # Peer registration
|
||||
│ └── app.py # Main API server
|
||||
├── webui/ # React frontend
|
||||
├── config/ # Configuration files
|
||||
├── data/ # Persistent data
|
||||
├── tests/ # Test suite
|
||||
└── docker-compose.yml # Container orchestration
|
||||
```
|
||||
|
||||
### **Running Locally**
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
pip install -r api/requirements.txt
|
||||
|
||||
# Start the API server
|
||||
python api/app.py
|
||||
|
||||
# Run tests
|
||||
python api/test_enhanced_api.py
|
||||
|
||||
# Start frontend (if available)
|
||||
cd webui && npm install && npm run dev
|
||||
```
|
||||
|
||||
### **Service Development**
|
||||
|
||||
```python
|
||||
from base_service_manager import BaseServiceManager
|
||||
|
||||
class MyServiceManager(BaseServiceManager):
|
||||
def __init__(self, data_dir='/app/data', config_dir='/app/config'):
|
||||
super().__init__('myservice', data_dir, config_dir)
|
||||
|
||||
def get_status(self) -> Dict[str, Any]:
|
||||
# Implement service status
|
||||
pass
|
||||
|
||||
def test_connectivity(self) -> Dict[str, Any]:
|
||||
# Implement connectivity test
|
||||
pass
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
### **Test Suite**
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
python api/test_enhanced_api.py
|
||||
|
||||
# Test specific components
|
||||
python -m pytest api/tests/test_network_manager.py
|
||||
python -m pytest api/tests/test_service_bus.py
|
||||
|
||||
# Coverage report
|
||||
coverage run -m pytest api/tests/
|
||||
coverage html
|
||||
```
|
||||
|
||||
### **Test Coverage**
|
||||
- **BaseServiceManager**: 100% coverage
|
||||
- **ConfigManager**: 95%+ coverage
|
||||
- **ServiceBus**: 95%+ coverage
|
||||
- **LogManager**: 95%+ coverage
|
||||
- **All Service Managers**: 77%+ overall coverage
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Deployment
|
||||
|
||||
### **Docker Deployment**
|
||||
|
||||
```bash
|
||||
# Production deployment
|
||||
docker-compose -f docker-compose.prod.yml up -d
|
||||
|
||||
# Development deployment
|
||||
docker-compose up --build
|
||||
```
|
||||
|
||||
### **System Requirements**
|
||||
- **CPU**: 2+ cores
|
||||
- **RAM**: 2GB+ (4GB recommended)
|
||||
- **Storage**: 10GB+ (SSD recommended)
|
||||
- **Network**: Stable internet connection
|
||||
|
||||
### **Monitoring**
|
||||
|
||||
```bash
|
||||
# Health check
|
||||
curl http://localhost:3000/health
|
||||
|
||||
# Service status
|
||||
curl http://localhost:3000/api/services/status
|
||||
|
||||
# Service connectivity
|
||||
curl http://localhost:3000/api/services/connectivity
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
1. **Fork** the repository
|
||||
2. **Create** a feature branch
|
||||
3. **Implement** your changes
|
||||
4. **Add tests** for new functionality
|
||||
5. **Submit** a pull request
|
||||
|
||||
### **Development Guidelines**
|
||||
- Follow the existing code style
|
||||
- Add comprehensive tests
|
||||
- Update documentation
|
||||
- Use the BaseServiceManager pattern
|
||||
- Implement proper error handling
|
||||
|
||||
---
|
||||
|
||||
## 📄 License
|
||||
|
||||
MIT License - see [LICENSE](LICENSE) file for details.
|
||||
|
||||
---
|
||||
|
||||
## 📚 Documentation
|
||||
|
||||
- **[Quick Start Guide](QUICKSTART.md)**: Get up and running quickly
|
||||
- **[API Documentation](api/API_DOCUMENTATION.md)**: Complete API reference
|
||||
- **[Comprehensive Improvements](COMPREHENSIVE_IMPROVEMENTS_SUMMARY.md)**: Detailed architecture overview
|
||||
- **[Enhanced API Improvements](ENHANCED_API_IMPROVEMENTS.md)**: Technical implementation details
|
||||
|
||||
---
|
||||
|
||||
**🌟 The Personal Internet Cell - Your self-hosted, production-grade digital infrastructure!**
|
||||
Reference in New Issue
Block a user