510 lines
10 KiB
Markdown
510 lines
10 KiB
Markdown
# Configuration Guide
|
|
|
|
## Environment Variables
|
|
|
|
Alle Konfiguration erfolgt über Environment Variables. Diese können gesetzt werden:
|
|
1. In `.env` Datei (lokale Entwicklung)
|
|
2. In systemd service file (production)
|
|
3. Export in shell
|
|
|
|
## Advoware API Configuration
|
|
|
|
### Required Variables
|
|
|
|
```bash
|
|
# Advoware API Base URL
|
|
ADVOWARE_API_BASE_URL=https://www2.advo-net.net:90/
|
|
|
|
# Product ID (typischerweise 64)
|
|
ADVOWARE_PRODUCT_ID=64
|
|
|
|
# Application ID (von Advoware bereitgestellt)
|
|
ADVOWARE_APP_ID=your_app_id_here
|
|
|
|
# API Key (Base64-encoded für HMAC-512 Signatur)
|
|
ADVOWARE_API_KEY=your_base64_encoded_key_here
|
|
|
|
# Kanzlei-Kennung
|
|
ADVOWARE_KANZLEI=your_kanzlei_name
|
|
|
|
# Database Name
|
|
ADVOWARE_DATABASE=your_database_name
|
|
|
|
# User für API-Zugriff
|
|
ADVOWARE_USER=api_user
|
|
|
|
# User Role (typischerweise 2)
|
|
ADVOWARE_ROLE=2
|
|
|
|
# User Password
|
|
ADVOWARE_PASSWORD=secure_password_here
|
|
|
|
# Token Lifetime in Minuten (Standard: 55)
|
|
ADVOWARE_TOKEN_LIFETIME_MINUTES=55
|
|
|
|
# API Timeout in Sekunden (Standard: 30)
|
|
ADVOWARE_API_TIMEOUT_SECONDS=30
|
|
|
|
# Write Protection (true = keine Schreibzugriffe auf Advoware)
|
|
ADVOWARE_WRITE_PROTECTION=true
|
|
```
|
|
|
|
### Advoware API Key
|
|
|
|
Der API Key muss Base64-encoded sein für HMAC-512 Signatur:
|
|
|
|
```bash
|
|
# Wenn Sie einen Raw Key haben, encodieren Sie ihn:
|
|
echo -n "your_raw_key" | base64
|
|
```
|
|
|
|
## Redis Configuration
|
|
|
|
```bash
|
|
# Redis Host (Standard: localhost)
|
|
REDIS_HOST=localhost
|
|
|
|
# Redis Port (Standard: 6379)
|
|
REDIS_PORT=6379
|
|
|
|
# Redis Database für Advoware Cache (Standard: 1)
|
|
REDIS_DB_ADVOWARE_CACHE=1
|
|
|
|
# Redis Database für Calendar Sync (Standard: 2)
|
|
REDIS_DB_CALENDAR_SYNC=2
|
|
|
|
# Redis Timeout in Sekunden (Standard: 5)
|
|
REDIS_TIMEOUT_SECONDS=5
|
|
```
|
|
|
|
### Redis Database Layout
|
|
|
|
- **DB 0**: Motia Framework (nicht konfigurierbar)
|
|
- **DB 1**: Advoware Cache & Locks (`REDIS_DB_ADVOWARE_CACHE`)
|
|
- Token Cache
|
|
- Employee Locks
|
|
- Webhook Deduplication
|
|
- **DB 2**: Calendar Sync Rate Limiting (`REDIS_DB_CALENDAR_SYNC`)
|
|
|
|
---
|
|
|
|
## KONG API Gateway Configuration
|
|
|
|
```bash
|
|
# KONG Admin API URL (für Konfiguration)
|
|
KONG_ADMIN_URL=http://localhost:8001
|
|
|
|
# KONG Proxy URL (öffentlich erreichbar)
|
|
KONG_PROXY_URL=https://api.bitbylaw.com
|
|
```
|
|
|
|
**Hinweis**: KONG-Konfiguration erfolgt typischerweise über Admin API oder Declarative Config (kong.yml).
|
|
|
|
---
|
|
|
|
## 3CX Telefonie Configuration
|
|
|
|
```bash
|
|
# 3CX API Base URL
|
|
THREECX_API_URL=https://ralup.my3cx.de/api/v1
|
|
|
|
# 3CX API Key für Authentifizierung
|
|
THREECX_API_KEY=your_3cx_api_key_here
|
|
|
|
# 3CX Webhook Secret (optional, für Signatur-Validierung)
|
|
THREECX_WEBHOOK_SECRET=your_webhook_secret_here
|
|
```
|
|
|
|
### 3CX Setup
|
|
|
|
1. Erstellen Sie API Key in 3CX Management Console
|
|
2. Konfigurieren Sie Webhook URLs in 3CX:
|
|
- Call Started: `https://api.bitbylaw.com/telephony/3cx/webhook`
|
|
- Call Ended: `https://api.bitbylaw.com/telephony/3cx/webhook`
|
|
3. Aktivieren Sie Call Recording (optional)
|
|
|
|
---
|
|
|
|
## Vermieterhelden Integration Configuration
|
|
|
|
```bash
|
|
# Vermieterhelden Webhook Secret (für Signatur-Validierung)
|
|
VH_WEBHOOK_SECRET=your_vermieterhelden_webhook_secret
|
|
|
|
# Lead Routing Target (wohin werden Leads geschickt)
|
|
VH_LEAD_TARGET=espocrm # Options: espocrm, advoware, both
|
|
|
|
# Lead Auto-Assignment (optional)
|
|
VH_AUTO_ASSIGN_LEADS=true
|
|
VH_DEFAULT_ASSIGNEE=user_id_123
|
|
```
|
|
|
|
### Vermieterhelden Setup
|
|
|
|
1. Konfigurieren Sie Webhook URL im WordPress:
|
|
- URL: `https://api.bitbylaw.com/leads/vermieterhelden`
|
|
2. Generieren Sie Shared Secret
|
|
3. Aktivieren Sie Webhook-Events für Lead-Erstellung
|
|
|
|
---
|
|
|
|
## Google Calendar Configuration
|
|
|
|
```bash
|
|
# Pfad zur Service Account JSON Datei
|
|
GOOGLE_CALENDAR_SERVICE_ACCOUNT_PATH=/opt/motia-app/service-account.json
|
|
|
|
# Google Calendar Scopes (Standard: calendar)
|
|
# GOOGLE_CALENDAR_SCOPES wird im Code gesetzt, keine ENV Variable nötig
|
|
```
|
|
|
|
### Service Account Setup
|
|
|
|
1. Erstellen Sie einen Service Account in Google Cloud Console
|
|
2. Laden Sie die JSON-Schlüsseldatei herunter
|
|
3. Speichern Sie sie als `service-account.json`
|
|
4. Setzen Sie sichere Berechtigungen:
|
|
|
|
```bash
|
|
chmod 600 /opt/motia-app/service-account.json
|
|
chown www-data:www-data /opt/motia-app/service-account.json
|
|
```
|
|
|
|
Siehe auch: [GOOGLE_SETUP_README.md](../GOOGLE_SETUP_README.md)
|
|
|
|
## PostgreSQL Configuration
|
|
|
|
**Status**: Aktuell nicht verwendet (zukünftige Erweiterung)
|
|
|
|
```bash
|
|
# PostgreSQL Host
|
|
POSTGRES_HOST=localhost
|
|
|
|
# PostgreSQL User
|
|
POSTGRES_USER=calendar_sync_user
|
|
|
|
# PostgreSQL Password
|
|
POSTGRES_PASSWORD=secure_password
|
|
|
|
# PostgreSQL Database Name
|
|
POSTGRES_DB_NAME=calendar_sync_db
|
|
```
|
|
|
|
## Calendar Sync Configuration
|
|
|
|
```bash
|
|
# Anonymisierung von Google Events (true/false)
|
|
CALENDAR_SYNC_ANONYMIZE_GOOGLE_EVENTS=true
|
|
|
|
# Debug: Nur bestimmte Mitarbeiter synchronisieren (Komma-separiert)
|
|
# Leer = alle Mitarbeiter
|
|
CALENDAR_SYNC_DEBUG_KUERZEL=SB,AI,RO,OK,BI,ST,UR,PB,VB
|
|
```
|
|
|
|
### Anonymisierung
|
|
|
|
Wenn `CALENDAR_SYNC_ANONYMIZE_GOOGLE_EVENTS=true`:
|
|
- Titel: "Blocked"
|
|
- Beschreibung: Leer
|
|
- Ort: Leer
|
|
|
|
Wenn `false`:
|
|
- Volle Details aus Advoware werden synchronisiert
|
|
|
|
### Debug-Modus
|
|
|
|
Für Development/Testing nur bestimmte Mitarbeiter synchronisieren:
|
|
|
|
```bash
|
|
# Nur diese Kürzel
|
|
CALENDAR_SYNC_DEBUG_KUERZEL=SB,AI
|
|
|
|
# Alle (Standard)
|
|
CALENDAR_SYNC_DEBUG_KUERZEL=
|
|
```
|
|
|
|
## EspoCRM Configuration
|
|
|
|
```bash
|
|
# API Key für Webhook-Validierung (optional)
|
|
ESPOCRM_MARVIN_API_KEY=your_webhook_secret_here
|
|
```
|
|
|
|
**Hinweis**: Aktuell wird der API Key nicht für Validierung verwendet. Zukünftige Implementierung kann HMAC-Signatur-Validierung hinzufügen.
|
|
|
|
## Motia Framework Configuration
|
|
|
|
```bash
|
|
# Node Environment (development|production)
|
|
NODE_ENV=production
|
|
|
|
# Node Memory Limit (in MB)
|
|
# NODE_OPTIONS wird in systemd gesetzt
|
|
NODE_OPTIONS=--max-old-space-size=8192 --inspect --heapsnapshot-signal=SIGUSR2
|
|
|
|
# Host Binding (0.0.0.0 = alle Interfaces)
|
|
HOST=0.0.0.0
|
|
|
|
# Port (Standard: 3000)
|
|
# PORT=3000
|
|
|
|
# Log Level (debug|info|warning|error)
|
|
MOTIA_LOG_LEVEL=debug
|
|
|
|
# npm Cache (für systemd user www-data)
|
|
NPM_CONFIG_CACHE=/opt/motia-app/.npm-cache
|
|
```
|
|
|
|
## Configuration Loading
|
|
|
|
### config.py
|
|
|
|
Zentrale Konfiguration wird in `config.py` geladen:
|
|
|
|
```python
|
|
from dotenv import load_dotenv
|
|
import os
|
|
|
|
# Load .env file if exists
|
|
load_dotenv()
|
|
|
|
class Config:
|
|
# Alle Variablen mit Defaults
|
|
REDIS_HOST = os.getenv('REDIS_HOST', 'localhost')
|
|
REDIS_PORT = int(os.getenv('REDIS_PORT', '6379'))
|
|
# ...
|
|
```
|
|
|
|
### Usage in Steps
|
|
|
|
```python
|
|
from config import Config
|
|
|
|
# Access configuration
|
|
redis_host = Config.REDIS_HOST
|
|
api_key = Config.ADVOWARE_API_KEY
|
|
```
|
|
|
|
### Usage in Services
|
|
|
|
```python
|
|
from config import Config
|
|
|
|
class AdvowareAPI:
|
|
def __init__(self):
|
|
self.api_key = Config.ADVOWARE_API_KEY
|
|
self.base_url = Config.ADVOWARE_API_BASE_URL
|
|
```
|
|
|
|
## Environment-Specific Configuration
|
|
|
|
### Development (.env)
|
|
|
|
Erstellen Sie eine `.env` Datei im Root:
|
|
|
|
```bash
|
|
# .env (nicht in Git committen!)
|
|
ADVOWARE_API_BASE_URL=https://staging.advo-net.net:90/
|
|
ADVOWARE_API_KEY=dev_key_here
|
|
REDIS_HOST=localhost
|
|
MOTIA_LOG_LEVEL=debug
|
|
ADVOWARE_WRITE_PROTECTION=true
|
|
```
|
|
|
|
**Wichtig**: `.env` zu `.gitignore` hinzufügen!
|
|
|
|
### Production (systemd)
|
|
|
|
In `/etc/systemd/system/motia.service`:
|
|
|
|
```ini
|
|
[Service]
|
|
Environment=NODE_ENV=production
|
|
Environment=ADVOWARE_API_BASE_URL=https://www2.advo-net.net:90/
|
|
Environment=ADVOWARE_API_KEY=production_key_here
|
|
Environment=ADVOWARE_PASSWORD=production_password_here
|
|
Environment=REDIS_HOST=localhost
|
|
Environment=MOTIA_LOG_LEVEL=info
|
|
Environment=ADVOWARE_WRITE_PROTECTION=false
|
|
```
|
|
|
|
Nach Änderungen:
|
|
```bash
|
|
sudo systemctl daemon-reload
|
|
sudo systemctl restart motia.service
|
|
```
|
|
|
|
### Staging
|
|
|
|
Eigene Service-Datei oder separate Environment-Datei.
|
|
|
|
## Validation
|
|
|
|
### Check Configuration
|
|
|
|
Script zum Validieren der Konfiguration:
|
|
|
|
```python
|
|
# scripts/check_config.py
|
|
from config import Config
|
|
import sys
|
|
|
|
required_vars = [
|
|
'ADVOWARE_API_BASE_URL',
|
|
'ADVOWARE_APP_ID',
|
|
'ADVOWARE_API_KEY',
|
|
'REDIS_HOST',
|
|
]
|
|
|
|
missing = []
|
|
for var in required_vars:
|
|
if not getattr(Config, var, None):
|
|
missing.append(var)
|
|
|
|
if missing:
|
|
print(f"ERROR: Missing configuration: {', '.join(missing)}")
|
|
sys.exit(1)
|
|
|
|
print("✓ Configuration valid")
|
|
```
|
|
|
|
Run:
|
|
```bash
|
|
python scripts/check_config.py
|
|
```
|
|
|
|
## Secrets Management
|
|
|
|
### DO NOT
|
|
|
|
❌ Commit secrets to Git
|
|
❌ Hardcode passwords in code
|
|
❌ Share `.env` files
|
|
❌ Log sensitive data
|
|
|
|
### DO
|
|
|
|
✅ Use environment variables
|
|
✅ Use `.gitignore` for `.env`
|
|
✅ Use systemd for production secrets
|
|
✅ Rotate keys regularly
|
|
✅ Use `chmod 600` for sensitive files
|
|
|
|
### Rotation
|
|
|
|
Wenn API Keys rotiert werden:
|
|
|
|
```bash
|
|
# 1. Update environment variable
|
|
sudo nano /etc/systemd/system/motia.service
|
|
|
|
# 2. Reload systemd
|
|
sudo systemctl daemon-reload
|
|
|
|
# 3. Clear Redis cache
|
|
redis-cli -n 1 DEL advoware_access_token advoware_token_timestamp
|
|
|
|
# 4. Restart service
|
|
sudo systemctl restart motia.service
|
|
|
|
# 5. Verify
|
|
sudo journalctl -u motia.service -f
|
|
```
|
|
|
|
## Configuration Reference
|
|
|
|
### Complete Example
|
|
|
|
```bash
|
|
# Advoware API
|
|
ADVOWARE_API_BASE_URL=https://www2.advo-net.net:90/
|
|
ADVOWARE_PRODUCT_ID=64
|
|
ADVOWARE_APP_ID=your_app_id
|
|
ADVOWARE_API_KEY=your_base64_key
|
|
ADVOWARE_KANZLEI=your_kanzlei
|
|
ADVOWARE_DATABASE=your_db
|
|
ADVOWARE_USER=api_user
|
|
ADVOWARE_ROLE=2
|
|
ADVOWARE_PASSWORD=your_password
|
|
ADVOWARE_TOKEN_LIFETIME_MINUTES=55
|
|
ADVOWARE_API_TIMEOUT_SECONDS=30
|
|
ADVOWARE_WRITE_PROTECTION=true
|
|
|
|
# Redis
|
|
REDIS_HOST=localhost
|
|
REDIS_PORT=6379
|
|
REDIS_DB_ADVOWARE_CACHE=1
|
|
REDIS_DB_CALENDAR_SYNC=2
|
|
REDIS_TIMEOUT_SECONDS=5
|
|
|
|
# Google Calendar
|
|
GOOGLE_CALENDAR_SERVICE_ACCOUNT_PATH=/opt/motia-app/service-account.json
|
|
|
|
# Calendar Sync
|
|
CALENDAR_SYNC_ANONYMIZE_GOOGLE_EVENTS=true
|
|
CALENDAR_SYNC_DEBUG_KUERZEL=
|
|
|
|
# PostgreSQL (optional)
|
|
POSTGRES_HOST=localhost
|
|
POSTGRES_USER=calendar_sync_user
|
|
POSTGRES_PASSWORD=your_pg_password
|
|
POSTGRES_DB_NAME=calendar_sync_db
|
|
|
|
# EspoCRM
|
|
ESPOCRM_MARVIN_API_KEY=your_webhook_key
|
|
|
|
# Motia
|
|
NODE_ENV=production
|
|
HOST=0.0.0.0
|
|
MOTIA_LOG_LEVEL=info
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### "Configuration not found"
|
|
|
|
```bash
|
|
# Check if .env exists
|
|
ls -la .env
|
|
|
|
# Check environment variables
|
|
env | grep ADVOWARE
|
|
|
|
# Check systemd environment
|
|
systemctl show motia.service -p Environment
|
|
```
|
|
|
|
### "Redis connection failed"
|
|
|
|
```bash
|
|
# Check Redis is running
|
|
sudo systemctl status redis-server
|
|
|
|
# Test connection
|
|
redis-cli -h $REDIS_HOST -p $REDIS_PORT ping
|
|
|
|
# Check config
|
|
echo "REDIS_HOST: $REDIS_HOST"
|
|
echo "REDIS_PORT: $REDIS_PORT"
|
|
```
|
|
|
|
### "API authentication failed"
|
|
|
|
```bash
|
|
# Check if API key is valid Base64
|
|
echo $ADVOWARE_API_KEY | base64 -d
|
|
|
|
# Clear token cache
|
|
redis-cli -n 1 DEL advoware_access_token
|
|
|
|
# Check logs
|
|
sudo journalctl -u motia.service | grep -i "token\|auth"
|
|
```
|
|
|
|
## Related Documentation
|
|
|
|
- [Development Guide](DEVELOPMENT.md)
|
|
- [Deployment Guide](DEPLOYMENT.md)
|
|
- [Troubleshooting](TROUBLESHOOTING.md)
|
|
- [Google Setup](../GOOGLE_SETUP_README.md)
|