giglez/docs/DEPLOYMENT_SUMMARY.md

# GigLez Deployment Strategy Summary

**Created**: 2026-01-12
**Purpose**: Quick reference for development vs production differences

---

## 🎯 Core Strategy: Hybrid Architecture

GigLez supports **two deployment modes** with shared codebase:

### Development Mode (Termux on Android)
```bash
GIGLEZ_MODE=development
```
- **Purpose**: Local wardriving with T-Embed hardware
- **Hardware**: USB serial + GPS access
- **Users**: Single user
- **Storage**: Local filesystem
- **Auth**: Optional
- **Database**: Local PostgreSQL (small pool: 5+5)
- **API**: localhost:8000
- **Background**: Synchronous processing

### Production Mode (Server/VPS)
```bash
GIGLEZ_MODE=production
```
- **Purpose**: Public multi-user platform
- **Hardware**: None (file uploads only)
- **Users**: Multi-user with authentication
- **Storage**: S3/MinIO object storage
- **Auth**: Required (JWT + API keys)
- **Database**: Remote PostgreSQL (large pool: 20+40)
- **API**: Public HTTPS with reverse proxy
- **Background**: Celery async tasks

---

## 📁 Configuration Files Created

### 1. `.env.development` ✅
For local Termux development:
- Small connection pool (5+5)
- Local filesystem storage
- Hardware access enabled
- Optional authentication
- DEBUG logging
- Offline queue support

### 2. `.env.production` ✅
For server deployment:
- Large connection pool (20+40)
- S3 object storage
- No hardware access
- Required authentication
- INFO logging
- Redis caching + Celery tasks

### 3. `config/settings.py` ✅
Environment-aware settings module:
- Automatic `.env` file selection
- Validation on startup
- Computed properties (is_production, use_redis, etc.)
- Type-safe enums for all options

---

## 🔑 Key Differences Table

| Aspect | Development | Production |
|--------|-------------|------------|
| **Database Pool** | 5 + 5 | 20 + 40 |
| **Storage** | Filesystem | S3/MinIO |
| **API Host** | 127.0.0.1 | 0.0.0.0 (behind proxy) |
| **Auth** | Optional | Required |
| **HTTPS** | Not needed | Required (Let's Encrypt) |
| **CORS** | `*` (permissive) | Strict whitelist |
| **Logging** | DEBUG, console | INFO, file + rotation |
| **Background** | Sync | Celery async |
| **Caching** | In-memory LRU | Redis + LRU |
| **Batch Size** | 256 | 512 |
| **Hardware** | T-Embed + GPS | None |
| **Offline Mode** | Enabled | Not applicable |

---

## 🚀 Quick Start Commands

### Development Setup (Termux)
```bash
# Copy development environment
cp .env.development .env

# Install dependencies
pip install -r requirements.txt

# Setup database
./scripts/setup_database.sh
psql -U giglez_user -d giglez -h localhost -f scripts/create_schema.sql

# Test configuration
python config/settings.py

# Start API
uvicorn src.api.main:app --host 127.0.0.1 --port 8000 --reload
```

### Production Setup (Server)
```bash
# Copy production environment
cp .env.production .env

# Edit with secure values
nano .env  # Change passwords, secrets, S3 credentials

# Install dependencies
pip install -r requirements.txt

# Setup database
./scripts/setup_database.sh
psql -U giglez_user -d giglez -h localhost -f scripts/create_schema.sql

# Install Redis
sudo apt install redis-server

# Install Nginx
sudo apt install nginx

# Configure SSL (Let's Encrypt)
sudo certbot --nginx -d giglez.com

# Start API (via systemd)
sudo systemctl start giglez
```

---

## 🎨 Architecture Pattern

### Modular Components
```
Core (Shared)           Capture Mode (Dev)      Platform Mode (Prod)
├── Database            ├── T-Embed USB         ├── Multi-user auth
├── Parser              ├── GPS integration     ├── Rate limiting
├── Matcher             ├── Auto-capture        ├── Celery tasks
├── GPS Validator       ├── Offline queue       ├── S3 storage
└── API Endpoints       └── Local storage       └── Monitoring
```

### Conditional Features
```python
from config.settings import settings

# Hardware endpoints (development only)
if settings.enable_hardware:
    @app.post("/api/capture/start")
    async def start_capture():
        """Only available in Termux mode"""
        pass

# Background tasks (mode-aware)
if settings.use_celery:
    celery_app.send_task('match_signatures', args=[file_hash])
else:
    match_signatures_sync(file_hash)
```

---

## 📊 Resource Requirements

### Development (Termux)
- **Device**: Android phone/tablet
- **RAM**: 2-4 GB
- **Storage**: 16-32 GB
- **Hardware**: LilyGo T-Embed (~$30-50)
- **Cost**: $0/month (one-time hardware cost)

### Production (Server)
- **VPS**: 2-8 GB RAM, 2-4 cores
- **Storage**: S3 ($0.02/GB/month) or filesystem
- **Database**: Included or managed service
- **Cost**: $10-80/month depending on scale

---

## 🔒 Security Differences

### Development
- Authentication optional (single user)
- No HTTPS required (localhost)
- No rate limiting needed
- Permissive CORS
- Debug endpoints enabled

### Production
- Authentication mandatory (JWT + API keys)
- HTTPS required (Let's Encrypt)
- Aggressive rate limiting
- Strict CORS whitelist
- Debug endpoints disabled
- Request validation
- SQL injection prevention (ORM)
- File upload size limits

---

## 🧪 Testing Strategy

### Shared Tests (Both Modes)
- Database operations
- .sub file parsing
- Signature matching
- GPS validation
- Query performance

### Development-Only Tests
- T-Embed serial communication
- GPS acquisition
- Offline queue processing
- Local file storage

### Production-Only Tests
- Multi-user authentication
- Rate limiting
- S3 storage integration
- Celery task processing
- API load testing

---

## 📝 Environment Variable Checklist

### Development Required ✅
- [x] `GIGLEZ_MODE=development`
- [x] `GIGLEZ_DB_HOST=localhost`
- [x] `GIGLEZ_STORAGE_PATH=/path/to/storage`
- [x] `GIGLEZ_ENABLE_HARDWARE=true`

### Production Required ✅
- [x] `GIGLEZ_MODE=production`
- [x] `GIGLEZ_DB_PASSWORD=CHANGE_THIS`
- [x] `GIGLEZ_JWT_SECRET_KEY=CHANGE_THIS`
- [x] `AWS_ACCESS_KEY_ID=your_key`
- [x] `AWS_SECRET_ACCESS_KEY=your_secret`
- [x] `GIGLEZ_REQUIRE_AUTH=true`

---

## 💡 Implementation Guidelines for Phase 2

### DO's ✅
- ✅ Write code that works in both modes by default
- ✅ Use `settings.is_production` for conditional features
- ✅ Abstract storage behind interface (filesystem/S3)
- ✅ Make authentication optional via settings
- ✅ Support both sync and async background processing
- ✅ Use environment variables for all configuration

### DON'Ts ❌
- ❌ Hard-code development/production differences
- ❌ Require hardware access in shared code
- ❌ Assume S3 storage everywhere
- ❌ Force authentication in development
- ❌ Require Celery for all background tasks
- ❌ Embed credentials in code

---

## 🎯 Phase 2 Ready

All configuration infrastructure is in place:

✅ Environment files (`.env.development`, `.env.production`)
✅ Settings module (`config/settings.py`)
✅ Validation on startup
✅ Mode detection
✅ Storage abstraction ready
✅ Background task abstraction ready
✅ Authentication flexibility

**Next Step**: Implement FastAPI application with environment-aware features

---

## 📚 Documentation Reference

- **Full Analysis**: `DEPLOYMENT_CONSIDERATIONS.md` (comprehensive guide)
- **This Summary**: `DEPLOYMENT_SUMMARY.md` (quick reference)
- **Environment Examples**: `.env.development`, `.env.production`
- **Settings Module**: `config/settings.py`

---

**Status**: Configuration Complete ✅
**Ready for**: Phase 2 FastAPI Implementation
**Approach**: Build once, deploy anywhere (development or production)