init
This commit is contained in:
Constantin
+358
@@ -0,0 +1,358 @@
|
||||
# Personal Internet Cell - Quick Start Guide
|
||||
|
||||
## 🚀 Getting Started
|
||||
|
||||
This guide will help you get your Personal Internet Cell up and running with the new production-grade architecture in minutes.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- **Docker and Docker Compose** installed
|
||||
- **Python 3.10+** (for CLI and development)
|
||||
- **Ports available**: 53, 80, 443, 3000, 51820
|
||||
- **Administrative access** (for WireGuard and network services)
|
||||
- **2GB+ RAM, 10GB+ disk space**
|
||||
|
||||
### Step 1: Initial Setup
|
||||
|
||||
```bash
|
||||
# Clone or download the project
|
||||
git clone https://github.com/yourusername/PersonalInternetCell.git
|
||||
cd PersonalInternetCell
|
||||
|
||||
# Start all services with Docker (Recommended)
|
||||
docker-compose up --build
|
||||
|
||||
# Or run locally
|
||||
pip install -r api/requirements.txt
|
||||
python api/app.py
|
||||
```
|
||||
|
||||
### Step 2: Verify Installation
|
||||
|
||||
```bash
|
||||
# Check if API is responding
|
||||
curl http://localhost:3000/health
|
||||
|
||||
# Check service status
|
||||
curl http://localhost:3000/api/services/status
|
||||
|
||||
# Use the enhanced CLI
|
||||
python api/enhanced_cli.py --status
|
||||
```
|
||||
|
||||
### Step 3: Explore Services
|
||||
|
||||
```bash
|
||||
# Show all services
|
||||
python api/enhanced_cli.py --services
|
||||
|
||||
# Check health data
|
||||
python api/enhanced_cli.py --health
|
||||
|
||||
# Interactive mode
|
||||
python api/enhanced_cli.py --interactive
|
||||
```
|
||||
|
||||
## 📋 Enhanced CLI Commands
|
||||
|
||||
### Basic Management
|
||||
```bash
|
||||
# Service status
|
||||
python api/enhanced_cli.py --status
|
||||
python api/enhanced_cli.py --services
|
||||
|
||||
# Health monitoring
|
||||
python api/enhanced_cli.py --health
|
||||
|
||||
# Service logs
|
||||
python api/enhanced_cli.py --logs network
|
||||
python api/enhanced_cli.py --logs wireguard
|
||||
```
|
||||
|
||||
### Configuration Management
|
||||
```bash
|
||||
# Export configuration
|
||||
python api/enhanced_cli.py --export-config json
|
||||
python api/enhanced_cli.py --export-config yaml
|
||||
|
||||
# Import configuration
|
||||
python api/enhanced_cli.py --import-config config.json
|
||||
|
||||
# Configuration wizard
|
||||
python api/enhanced_cli.py --wizard network
|
||||
python api/enhanced_cli.py --wizard email
|
||||
```
|
||||
|
||||
### Batch Operations
|
||||
```bash
|
||||
# Execute multiple commands
|
||||
python api/enhanced_cli.py --batch "status" "services" "health"
|
||||
|
||||
# Interactive mode with tab completion
|
||||
python api/enhanced_cli.py --interactive
|
||||
```
|
||||
|
||||
## 🌐 Accessing Services
|
||||
|
||||
Once running, you can access:
|
||||
|
||||
- **API Server**: http://localhost:3000
|
||||
- **API Health**: http://localhost:3000/health
|
||||
- **Service Status**: http://localhost:3000/api/services/status
|
||||
- **Configuration**: http://localhost:3000/api/config
|
||||
- **Service Bus**: http://localhost:3000/api/services/bus/status
|
||||
- **Logs**: http://localhost:3000/api/logs/services/network
|
||||
|
||||
## 🔧 Configuration
|
||||
|
||||
### Cell Configuration
|
||||
|
||||
The cell uses a centralized configuration system with schema validation:
|
||||
|
||||
```bash
|
||||
# View current configuration
|
||||
curl 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",
|
||||
"ip_range": "10.0.0.0/24",
|
||||
"wireguard_port": 51820
|
||||
}'
|
||||
```
|
||||
|
||||
### Service Configuration
|
||||
|
||||
Each service has its own configuration schema:
|
||||
|
||||
```bash
|
||||
# Network configuration
|
||||
python api/enhanced_cli.py --wizard network
|
||||
|
||||
# Email configuration
|
||||
python api/enhanced_cli.py --wizard email
|
||||
|
||||
# WireGuard configuration
|
||||
python api/enhanced_cli.py --wizard wireguard
|
||||
```
|
||||
|
||||
### Network Configuration
|
||||
The cell uses the following network ranges:
|
||||
- **Cell Network**: 10.0.0.0/24 (configurable)
|
||||
- **DHCP Range**: 10.0.0.100-10.0.0.200 (configurable)
|
||||
- **WireGuard Port**: 51820/UDP (configurable)
|
||||
- **API Port**: 3000 (configurable)
|
||||
|
||||
## 🔗 Adding Peers
|
||||
|
||||
### 1. Generate WireGuard Keys (on peer cell)
|
||||
```bash
|
||||
wg genkey | tee private.key | wg pubkey > public.key
|
||||
```
|
||||
|
||||
### 2. Add Peer to Your Cell
|
||||
```bash
|
||||
# Using the enhanced CLI
|
||||
python api/enhanced_cli.py --batch "add-peer bob 203.0.113.22 $(cat public.key)"
|
||||
|
||||
# Or via API
|
||||
curl -X POST http://localhost:3000/api/wireguard/peers \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "bob",
|
||||
"ip": "203.0.113.22",
|
||||
"public_key": "your_public_key_here"
|
||||
}'
|
||||
```
|
||||
|
||||
### 3. Configure Routing Rules
|
||||
```bash
|
||||
# Allow peer to access your LAN
|
||||
curl -X POST http://localhost:3000/api/routing/peers \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"peer_name": "bob",
|
||||
"peer_ip": "203.0.113.22",
|
||||
"allowed_networks": ["10.0.0.0/24"],
|
||||
"route_type": "lan"
|
||||
}'
|
||||
|
||||
# Allow peer to use your cell as exit node
|
||||
curl -X POST http://localhost:3000/api/routing/exit-nodes \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"peer_name": "bob",
|
||||
"peer_ip": "203.0.113.22",
|
||||
"allowed_domains": ["google.com", "github.com"]
|
||||
}'
|
||||
```
|
||||
|
||||
## 🔍 Troubleshooting
|
||||
|
||||
### Services Not Starting
|
||||
```bash
|
||||
# Check Docker logs
|
||||
docker-compose logs
|
||||
|
||||
# Check individual service
|
||||
docker-compose logs api
|
||||
docker-compose logs wireguard
|
||||
|
||||
# Check service status via API
|
||||
curl http://localhost:3000/api/services/status
|
||||
```
|
||||
|
||||
### API Issues
|
||||
```bash
|
||||
# Test API health
|
||||
curl http://localhost:3000/health
|
||||
|
||||
# Check service connectivity
|
||||
curl http://localhost:3000/api/services/connectivity
|
||||
|
||||
# View API logs
|
||||
python api/enhanced_cli.py --logs api
|
||||
```
|
||||
|
||||
### Network Issues
|
||||
```bash
|
||||
# Test DNS resolution
|
||||
nslookup google.com 127.0.0.1
|
||||
|
||||
# Check network service status
|
||||
curl http://localhost:3000/api/dns/status
|
||||
curl http://localhost:3000/api/network/info
|
||||
|
||||
# Test network connectivity
|
||||
curl -X POST http://localhost:3000/api/network/test \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"target": "8.8.8.8"}'
|
||||
```
|
||||
|
||||
### WireGuard Issues
|
||||
```bash
|
||||
# Check WireGuard status
|
||||
curl http://localhost:3000/api/wireguard/status
|
||||
|
||||
# Test WireGuard connectivity
|
||||
curl -X POST http://localhost:3000/api/wireguard/connectivity \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"target_ip": "203.0.113.22"}'
|
||||
|
||||
# View WireGuard logs
|
||||
python api/enhanced_cli.py --logs wireguard
|
||||
```
|
||||
|
||||
### Configuration Issues
|
||||
```bash
|
||||
# Validate configuration
|
||||
curl http://localhost:3000/api/config
|
||||
|
||||
# Backup and restore
|
||||
curl -X POST http://localhost:3000/api/config/backup
|
||||
curl -X POST http://localhost:3000/api/config/restore/backup_id
|
||||
|
||||
# Export/import configuration
|
||||
python api/enhanced_cli.py --export-config json
|
||||
python api/enhanced_cli.py --import-config config.json
|
||||
```
|
||||
|
||||
## 📁 File Structure
|
||||
|
||||
```
|
||||
PersonalInternetCell/
|
||||
├── docker-compose.yml # Main orchestration
|
||||
├── api/ # API server and service managers
|
||||
│ ├── 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
|
||||
│ └── test_enhanced_api.py # Comprehensive test suite
|
||||
├── config/ # Configuration files
|
||||
│ ├── cell.json # Cell configuration
|
||||
│ ├── network.json # Network service config
|
||||
│ ├── wireguard.json # WireGuard config
|
||||
│ └── ...
|
||||
├── data/ # Persistent data
|
||||
│ ├── api/ # API data
|
||||
│ ├── dns/ # DNS zones
|
||||
│ ├── email/ # Email data
|
||||
│ ├── calendar/ # Calendar data
|
||||
│ ├── files/ # File storage
|
||||
│ ├── vault/ # Certificates and keys
|
||||
│ └── logs/ # Service logs
|
||||
└── webui/ # React frontend (if available)
|
||||
```
|
||||
|
||||
## 🔒 Security Notes
|
||||
|
||||
- **Self-hosted CA**: The cell generates and manages its own certificates
|
||||
- **WireGuard keys**: Generated automatically with secure key management
|
||||
- **Service isolation**: All services run in isolated Docker containers
|
||||
- **Encrypted storage**: Sensitive data encrypted using Age/Fernet
|
||||
- **Trust management**: Peer trust relationships with cryptographic verification
|
||||
- **Configuration validation**: All configuration validated against schemas
|
||||
|
||||
## 🆘 Getting Help
|
||||
|
||||
### Diagnostic Commands
|
||||
```bash
|
||||
# Comprehensive status check
|
||||
python api/enhanced_cli.py --status
|
||||
|
||||
# Service health check
|
||||
python api/enhanced_cli.py --health
|
||||
|
||||
# Service logs
|
||||
python api/enhanced_cli.py --logs network
|
||||
|
||||
# Configuration validation
|
||||
curl http://localhost:3000/api/config
|
||||
|
||||
# Service connectivity test
|
||||
curl http://localhost:3000/api/services/connectivity
|
||||
```
|
||||
|
||||
### Common Issues
|
||||
1. **Port conflicts**: Ensure ports 53, 3000, 51820 are available
|
||||
2. **Permission issues**: Run with appropriate privileges for network services
|
||||
3. **Configuration errors**: Use the configuration wizard for guided setup
|
||||
4. **Service dependencies**: Check service bus status for dependency issues
|
||||
|
||||
## 🚀 Next Steps
|
||||
|
||||
After basic setup, consider:
|
||||
|
||||
1. **Customizing your cell name** and domain configuration
|
||||
2. **Adding trusted peers** for mesh networking
|
||||
3. **Configuring email services** with your domain
|
||||
4. **Setting up file storage** and user management
|
||||
5. **Implementing backup strategies** for configuration and data
|
||||
6. **Exploring advanced routing** features (exit nodes, bridge routing)
|
||||
7. **Setting up monitoring** and alerting for service health
|
||||
|
||||
## 📚 Additional Resources
|
||||
|
||||
- **[API Documentation](api/API_DOCUMENTATION.md)**: Complete API reference
|
||||
- **[Comprehensive Improvements](COMPREHENSIVE_IMPROVEMENTS_SUMMARY.md)**: Architecture overview
|
||||
- **[Enhanced API Improvements](ENHANCED_API_IMPROVEMENTS.md)**: Technical details
|
||||
- **[Project Wiki](Personal%20Internet%20Cell%20–%20Project%20Wiki.md)**: Detailed project information
|
||||
|
||||
---
|
||||
|
||||
**🌟 Happy networking with your Personal Internet Cell!**
|
||||
Reference in New Issue
Block a user