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

# 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

# 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

# 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

# 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

# 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

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

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

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

wg genkey | tee private.key | wg pubkey > public.key

2. Add Peer to Your Cell

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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: Complete API reference
• Comprehensive Improvements: Architecture overview
• Enhanced API Improvements: Technical details
• Project Wiki: Detailed project information

---

🌟 Happy networking with your Personal Internet Cell!