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

git clone https://git.colsys.tech/COLSYS/geutebruck-api.git
cd geutebruck-api

2. Configure Environment

Copy .env.example to .env:

copy .env.example .env

Edit .env with your configuration:

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

python -c "import secrets; print(secrets.token_urlsafe(32))"

3. Install Dependencies

Python API

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

SDK Bridge (.NET)

cd src\sdk-bridge
dotnet restore
dotnet build --configuration Release

4. Setup Database

Create PostgreSQL database:

CREATE DATABASE geutebruck_api;
CREATE USER geutebruck WITH PASSWORD 'secure_password';
GRANT ALL PRIVILEGES ON DATABASE geutebruck_api TO geutebruck;

Run migrations:

cd src\api
alembic upgrade head

Default Admin User Created:

• Username: admin
• Password: admin123
• ⚠️ CHANGE THIS IMMEDIATELY IN PRODUCTION

5. Verify Redis

redis-cli ping
# Should return: PONG

---

Running Services

Development Mode

Terminal 1: SDK Bridge

cd src\sdk-bridge\GeViScopeBridge
dotnet run

Terminal 2: Python API

cd src\api
python main.py

Production Mode

SDK Bridge (Windows Service)

Create Windows Service using NSSM (Non-Sucking Service Manager):

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

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

Option 3: Docker (Recommended)

docker-compose up -d

---

Health Checks

Verify all components are healthy:

curl http://localhost:8000/health

Expected response:

{
  "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:

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:

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

pg_dump -U geutebruck geutebruck_api > backup.sql

Restore:

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:

cd src\api
alembic upgrade head

Dependency Updates

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