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)

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)

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)

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

# 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

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 ✅

• GIGLEZ_MODE=development
• GIGLEZ_DB_HOST=localhost
• GIGLEZ_STORAGE_PATH=/path/to/storage
• GIGLEZ_ENABLE_HARDWARE=true

Production Required ✅

• GIGLEZ_MODE=production
• GIGLEZ_DB_PASSWORD=CHANGE_THIS
• GIGLEZ_JWT_SECRET_KEY=CHANGE_THIS
• AWS_ACCESS_KEY_ID=your_key
• AWS_SECRET_ACCESS_KEY=your_secret
• 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)