Initial commit: Phase 1 & Phase 2 infrastructure complete
This commit is contained in:
@@ -0,0 +1,298 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user