Phase 8: MVP Polish - COMPLETE (T075-T084)
🎉 MVP v1.0.0 COMPLETE! 🎉 Final polishing phase with comprehensive documentation and enhanced monitoring: **Enhanced Monitoring:** - Enhanced health check endpoint with component-level status - Database connectivity check (PostgreSQL) - Redis connectivity check - SDK Bridge connectivity check (gRPC) - Overall status (healthy/degraded) - Metrics endpoint with route counts and feature flags - Updated root endpoint with metrics link **Comprehensive Documentation:** - API Reference (docs/api-reference.md) - Complete endpoint documentation - Request/response examples - Authentication guide - Error responses - RBAC table - Deployment Guide (docs/deployment.md) - Prerequisites and system requirements - Installation instructions - Database setup and migrations - Production deployment (Windows Service/IIS/Docker) - Security hardening - Monitoring and alerts - Backup and recovery - Troubleshooting - Usage Guide (docs/usage-guide.md) - Practical examples with curl - Common operations - Use case scenarios - Python and C# client examples - Postman testing guide - Best practices - Release Notes (RELEASE_NOTES.md) - Complete MVP feature list - Architecture overview - Technology stack - Installation quick start - Testing coverage - Security considerations - Known limitations - Future roadmap **MVP Deliverables:** ✅ 21 API endpoints ✅ 84 tasks completed ✅ 213 test cases ✅ 3-tier architecture (API + SDK Bridge + GeViServer) ✅ JWT authentication with RBAC ✅ Cross-switching control (CORE FEATURE) ✅ Camera/monitor discovery ✅ Routing state management ✅ Audit logging ✅ Redis caching ✅ PostgreSQL persistence ✅ Comprehensive documentation **Core Functionality:** - Execute cross-switch (route camera to monitor) - Clear monitor (remove camera) - Query routing state (active routes) - Routing history with pagination - RBAC enforcement (Operator required for execution) **Out of Scope (Intentional):** ❌ Recording management ❌ Video analytics ❌ LPR/NPR ❌ PTZ control ❌ Live streaming 🚀 Ready for deployment and testing! 🚀 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Geutebruck API Developer
377
docs/deployment.md
Normal file
377
docs/deployment.md
Normal file
@@ -0,0 +1,377 @@
|
||||
# Deployment Guide
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Required Software
|
||||
- **Python**: 3.10+ (tested with 3.11)
|
||||
- **.NET**: .NET 8.0 SDK (for SDK Bridge)
|
||||
- **.NET Framework**: 4.8 Runtime (for GeViScope SDK)
|
||||
- **PostgreSQL**: 14+
|
||||
- **Redis**: 6.0+
|
||||
- **GeViServer**: GeViScope/GeViSoft installation
|
||||
|
||||
### System Requirements
|
||||
- **OS**: Windows Server 2019+ or Windows 10/11
|
||||
- **RAM**: 4GB minimum, 8GB recommended
|
||||
- **Disk**: 10GB free space
|
||||
- **Network**: Access to GeViServer and PostgreSQL/Redis
|
||||
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
### 1. Clone Repository
|
||||
|
||||
```bash
|
||||
git clone https://git.colsys.tech/COLSYS/geutebruck-api.git
|
||||
cd geutebruck-api
|
||||
```
|
||||
|
||||
### 2. Configure Environment
|
||||
|
||||
Copy `.env.example` to `.env`:
|
||||
|
||||
```bash
|
||||
copy .env.example .env
|
||||
```
|
||||
|
||||
Edit `.env` with your configuration:
|
||||
|
||||
```env
|
||||
# API
|
||||
API_HOST=0.0.0.0
|
||||
API_PORT=8000
|
||||
API_TITLE=Geutebruck Cross-Switching API
|
||||
API_VERSION=1.0.0
|
||||
ENVIRONMENT=production
|
||||
|
||||
# SDK Bridge
|
||||
SDK_BRIDGE_HOST=localhost
|
||||
SDK_BRIDGE_PORT=50051
|
||||
|
||||
# GeViServer
|
||||
GEVISERVER_HOST=your-geviserver-hostname
|
||||
GEVISERVER_USERNAME=sysadmin
|
||||
GEVISERVER_PASSWORD=your-password-here
|
||||
|
||||
# Database
|
||||
DATABASE_URL=postgresql+asyncpg://geutebruck:secure_password@localhost:5432/geutebruck_api
|
||||
|
||||
# Redis
|
||||
REDIS_HOST=localhost
|
||||
REDIS_PORT=6379
|
||||
|
||||
# JWT
|
||||
JWT_SECRET_KEY=generate-a-secure-random-key-here
|
||||
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=60
|
||||
JWT_REFRESH_TOKEN_EXPIRE_DAYS=7
|
||||
|
||||
# Security
|
||||
CORS_ORIGINS=["http://localhost:3000"]
|
||||
|
||||
# Logging
|
||||
LOG_FORMAT=json
|
||||
LOG_LEVEL=INFO
|
||||
```
|
||||
|
||||
**IMPORTANT**: Generate secure `JWT_SECRET_KEY`:
|
||||
```bash
|
||||
python -c "import secrets; print(secrets.token_urlsafe(32))"
|
||||
```
|
||||
|
||||
### 3. Install Dependencies
|
||||
|
||||
#### Python API
|
||||
|
||||
```bash
|
||||
python -m venv .venv
|
||||
.venv\Scripts\activate
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
#### SDK Bridge (.NET)
|
||||
|
||||
```bash
|
||||
cd src\sdk-bridge
|
||||
dotnet restore
|
||||
dotnet build --configuration Release
|
||||
```
|
||||
|
||||
### 4. Setup Database
|
||||
|
||||
Create PostgreSQL database:
|
||||
|
||||
```sql
|
||||
CREATE DATABASE geutebruck_api;
|
||||
CREATE USER geutebruck WITH PASSWORD 'secure_password';
|
||||
GRANT ALL PRIVILEGES ON DATABASE geutebruck_api TO geutebruck;
|
||||
```
|
||||
|
||||
Run migrations:
|
||||
|
||||
```bash
|
||||
cd src\api
|
||||
alembic upgrade head
|
||||
```
|
||||
|
||||
**Default Admin User Created:**
|
||||
- Username: `admin`
|
||||
- Password: `admin123`
|
||||
- **⚠️ CHANGE THIS IMMEDIATELY IN PRODUCTION**
|
||||
|
||||
### 5. Verify Redis
|
||||
|
||||
```bash
|
||||
redis-cli ping
|
||||
# Should return: PONG
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Running Services
|
||||
|
||||
### Development Mode
|
||||
|
||||
#### Terminal 1: SDK Bridge
|
||||
```bash
|
||||
cd src\sdk-bridge\GeViScopeBridge
|
||||
dotnet run
|
||||
```
|
||||
|
||||
#### Terminal 2: Python API
|
||||
```bash
|
||||
cd src\api
|
||||
python main.py
|
||||
```
|
||||
|
||||
### Production Mode
|
||||
|
||||
#### SDK Bridge (Windows Service)
|
||||
|
||||
Create Windows Service using NSSM (Non-Sucking Service Manager):
|
||||
|
||||
```bash
|
||||
nssm install GeViScopeBridge "C:\path\to\dotnet.exe"
|
||||
nssm set GeViScopeBridge AppDirectory "C:\path\to\geutebruck-api\src\sdk-bridge\GeViScopeBridge"
|
||||
nssm set GeViScopeBridge AppParameters "run --no-launch-profile"
|
||||
nssm set GeViScopeBridge DisplayName "GeViScope SDK Bridge"
|
||||
nssm set GeViScopeBridge Start SERVICE_AUTO_START
|
||||
nssm start GeViScopeBridge
|
||||
```
|
||||
|
||||
#### Python API (Windows Service/IIS)
|
||||
|
||||
**Option 1: Windows Service with NSSM**
|
||||
```bash
|
||||
nssm install GeutebruckAPI "C:\path\to\.venv\Scripts\python.exe"
|
||||
nssm set GeutebruckAPI AppDirectory "C:\path\to\geutebruck-api\src\api"
|
||||
nssm set GeutebruckAPI AppParameters "main.py"
|
||||
nssm set GeutebruckAPI DisplayName "Geutebruck API"
|
||||
nssm set GeutebruckAPI Start SERVICE_AUTO_START
|
||||
nssm start GeutebruckAPI
|
||||
```
|
||||
|
||||
**Option 2: IIS with FastCGI**
|
||||
- Install IIS with CGI module
|
||||
- Install wfastcgi
|
||||
- Configure IIS to run FastAPI application
|
||||
- See [Microsoft FastAPI IIS guide](https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/iis/)
|
||||
|
||||
**Option 3: Docker (Recommended)**
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Health Checks
|
||||
|
||||
Verify all components are healthy:
|
||||
|
||||
```bash
|
||||
curl http://localhost:8000/health
|
||||
```
|
||||
|
||||
Expected response:
|
||||
```json
|
||||
{
|
||||
"status": "healthy",
|
||||
"version": "1.0.0",
|
||||
"environment": "production",
|
||||
"components": {
|
||||
"database": {"status": "healthy", "type": "postgresql"},
|
||||
"redis": {"status": "healthy", "type": "redis"},
|
||||
"sdk_bridge": {"status": "healthy", "type": "grpc"}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security Hardening
|
||||
|
||||
### 1. Change Default Credentials
|
||||
|
||||
**Admin User:**
|
||||
```python
|
||||
from passlib.hash import bcrypt
|
||||
new_password_hash = bcrypt.hash("your-new-secure-password")
|
||||
# Update in database: UPDATE users SET password_hash = '...' WHERE username = 'admin';
|
||||
```
|
||||
|
||||
### 2. Configure HTTPS
|
||||
|
||||
Use reverse proxy (nginx, IIS) with SSL certificate:
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 443 ssl;
|
||||
server_name api.your-domain.com;
|
||||
|
||||
ssl_certificate /path/to/cert.pem;
|
||||
ssl_certificate_key /path/to/key.pem;
|
||||
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:8000;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Firewall Rules
|
||||
|
||||
- **API**: Allow port 8000 only from trusted networks
|
||||
- **SDK Bridge**: Port 50051 localhost only
|
||||
- **PostgreSQL**: Port 5432 localhost only
|
||||
- **Redis**: Port 6379 localhost only
|
||||
|
||||
### 4. Environment Variables
|
||||
|
||||
Store sensitive values in secure vault (Azure Key Vault, AWS Secrets Manager, etc.)
|
||||
|
||||
---
|
||||
|
||||
## Monitoring
|
||||
|
||||
### Logs
|
||||
|
||||
**Python API:**
|
||||
- Location: `logs/api.log`
|
||||
- Format: JSON (structured logging with structlog)
|
||||
- Rotation: Configure in production
|
||||
|
||||
**SDK Bridge:**
|
||||
- Location: `logs/sdk-bridge.log`
|
||||
- Format: Serilog JSON
|
||||
- Rotation: Daily
|
||||
|
||||
### Metrics
|
||||
|
||||
- Endpoint: `GET /metrics`
|
||||
- Consider adding Prometheus exporter for production
|
||||
|
||||
### Alerts
|
||||
|
||||
Configure alerts for:
|
||||
- Health check failures
|
||||
- SDK Bridge disconnections
|
||||
- Database connection failures
|
||||
- High error rates in audit logs
|
||||
|
||||
---
|
||||
|
||||
## Backup & Recovery
|
||||
|
||||
### Database Backup
|
||||
|
||||
```bash
|
||||
pg_dump -U geutebruck geutebruck_api > backup.sql
|
||||
```
|
||||
|
||||
Restore:
|
||||
```bash
|
||||
psql -U geutebruck geutebruck_api < backup.sql
|
||||
```
|
||||
|
||||
### Configuration Backup
|
||||
|
||||
Backup `.env` and `appsettings.json` files securely.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### SDK Bridge Connection Failed
|
||||
|
||||
1. Check GeViServer is reachable
|
||||
2. Verify credentials in `.env`
|
||||
3. Check SDK Bridge logs
|
||||
4. Test SDK connection manually
|
||||
|
||||
### Database Connection Issues
|
||||
|
||||
1. Verify PostgreSQL is running
|
||||
2. Check connection string in `.env`
|
||||
3. Test connection: `psql -U geutebruck geutebruck_api`
|
||||
|
||||
### Redis Connection Issues
|
||||
|
||||
1. Verify Redis is running: `redis-cli ping`
|
||||
2. Check Redis host/port in `.env`
|
||||
|
||||
### Authentication Failures
|
||||
|
||||
1. Check JWT_SECRET_KEY is set
|
||||
2. Verify token expiration times
|
||||
3. Check audit logs for failed login attempts
|
||||
|
||||
---
|
||||
|
||||
## Scaling
|
||||
|
||||
### Horizontal Scaling
|
||||
|
||||
- Run multiple API instances behind load balancer
|
||||
- Share Redis and PostgreSQL instances
|
||||
- Run single SDK Bridge instance per GeViServer
|
||||
|
||||
### Vertical Scaling
|
||||
|
||||
- Increase database connection pool size
|
||||
- Increase Redis max connections
|
||||
- Allocate more CPU/RAM to API process
|
||||
|
||||
---
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Database Migrations
|
||||
|
||||
When updating code with new migrations:
|
||||
|
||||
```bash
|
||||
cd src\api
|
||||
alembic upgrade head
|
||||
```
|
||||
|
||||
### Dependency Updates
|
||||
|
||||
```bash
|
||||
pip install --upgrade -r requirements.txt
|
||||
dotnet restore
|
||||
```
|
||||
|
||||
### Log Rotation
|
||||
|
||||
Configure logrotate (Linux) or Windows Task Scheduler to rotate logs weekly.
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions:
|
||||
- **GitHub Issues**: https://github.com/anthropics/claude-code/issues
|
||||
- **Documentation**: See `docs/` directory
|
||||
- **API Reference**: http://localhost:8000/docs
|
||||
Reference in New Issue
Block a user