roof/pic
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2277b11563a6bfaa2520ce6c9a4d95163043dbc1
pic/README.md
T
Constantin 2277b11563 init
2025-09-12 23:04:52 +03:00

463 lines
13 KiB
Markdown
Raw Blame History

# 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 View Git Blame Copy Permalink