bsiggel/motia
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
64b8c8f36696a1d34721bf472fe302cc5fa74e01
motia/bitbylaw/docs/CONFIGURATION.md
bitbylaw 36552903e7 cleanup
2026-02-07 09:23:49 +00:00

10 KiB
Raw Blame History

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

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

# Wenn Sie einen Raw Key haben, encodieren Sie ihn:
echo -n "your_raw_key" | base64

Redis Configuration

# 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

# 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

# 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

# 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

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

PostgreSQL Configuration

Status: Aktuell nicht verwendet (zukünftige Erweiterung)

# 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

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

# Nur diese Kürzel
CALENDAR_SYNC_DEBUG_KUERZEL=SB,AI

# Alle (Standard)
CALENDAR_SYNC_DEBUG_KUERZEL=

EspoCRM Configuration

# 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

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

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

from config import Config

# Access configuration
redis_host = Config.REDIS_HOST
api_key = Config.ADVOWARE_API_KEY

Usage in Services

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:

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

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

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:

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

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:

# 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

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

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

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

# 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

Reference in New Issue View Git Blame Copy Permalink