pic/QUICKSTART.md

# 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!**