geutebruck/geutebruck-api/docs/deployment.md

# 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