Configuration reference

This reference documents all configuration options for the four Iqra AI services. Each service uses an appsettings.json file for configuration.

Some configuration blocks must be identical across all services (marked as “SHARED”). Mismatched values will cause communication failures between services.

Configuration files

Each service has its own configuration file:

ProjectIqraFrontend/appsettings.json - Dashboard and API
ProjectIqraBackendProxy/appsettings.json - Load balancer and SIP gateway
ProjectIqraBackendApp/appsettings.json - Core agent engine
IqraBackgroundProcessor/appsettings.json - Async processing

Example files are provided as appsettings.json.example in each directory.

Frontend configuration

URL

{
  "URL": "https://app.iqra.bot"
}

Purpose: The public URL where the dashboard is hosted (without trailing slash). Used for:

Email links (password resets, invitations)
Webhook URL generation
OAuth redirects

Hardware

{
  "Hardware": {
    "NetworkInterfaceName": "eth0"
  }
}

string

required

The OS-level name of the network interface for RTP audio (UDP) binding.How to find:

Linux: ip addr (e.g., eth0, ens5, ens160)
Windows: ipconfig (e.g., "Ethernet", "vEthernet (WSL)")

S3 Storage

{
  "S3Storage": {
    "DefaultStorageRegionId": "us-east-1"
  }
}

string

required

The Region ID where default assets are stored. This must match a Region created in the Admin Dashboard under Infrastructure → Regions.Used for:

Logo uploads
Call recordings
Document uploads for knowledge bases

Redis (SHARED)

{
  "RedisDatabase": {
    "Endpoint": "localhost:6379",
    "Password": ""
  }
}

This configuration must be identical across Frontend, Proxy, Backend, and Processor.

string

required

Redis connection endpoint in host:port format.

string

Redis authentication password. Leave empty ("") if no password is set.

MongoDB (SHARED)

{
  "MongoDatabase": {
    "ConnectionString": "mongodb://localhost:27017"
  }
}

This configuration must be identical across all services.

string

required

MongoDB connection string. Supports:

Standalone: mongodb://localhost:27017
Replica set: mongodb://host1:27017,host2:27017,host3:27017/?replicaSet=rs0
Authentication: mongodb://username:password@host:27017/dbname

Milvus (SHARED)

{
  "Milvus": {
    "Endpoint": "http://localhost:9091",
    "Database": "iqra",
    "Username": "root",
    "Password": "Milvus",
    "ExpiryCheckIntervalSeconds": 300,
    "CollectionStaleTimeoutMinutes": 30
  }
}

This configuration must be identical across Frontend, Backend, and Processor.

string

required

HTTP URL for the Milvus vector database. Usually port 19530 (gRPC) or 9091 (HTTP).

string

required

Database name inside Milvus to store embeddings.

string

required

Milvus authentication username (default: root).

string

required

Milvus authentication password (default: Milvus).

integer

How often (in seconds) to check for expired vector collections. Default: 300 (5 minutes).

integer

Time (in minutes) before an unused collection is unloaded from memory. Default: 30.

Unstructured

{
  "Unstructured": {
    "EndPoint": "http://localhost:8741",
    "ApiKey": "<your_api_key>"
  }
}

string

required

URL for the Unstructured.io ETL service used for parsing documents (PDFs, DOCX, etc.) for knowledge bases.Options:

Self-hosted Docker container: http://localhost:8741
Unstructured SaaS: https://api.unstructured.io

string

API key for Unstructured service (required for SaaS version or secured containers).

Mail SMTP

{
  "MailSMTP": {
    "Host": "smtp.sendgrid.net",
    "Port": 587,
    "Username": "apikey",
    "Password": "SG.xxxxx",
    "FromEmail": "noreply@iqra.bot",
    "FromName": "Iqra AI"
  }
}

string

required

SMTP server hostname (e.g., smtp.sendgrid.net, smtp.gmail.com, smtp.mailgun.org).

integer

required

SMTP port. Common values:

587 - STARTTLS (recommended)
465 - SSL
25 - Unencrypted (not recommended)

string

required

SMTP authentication username.

string

required

SMTP authentication password or API key.

string

required

Email address for the “From” field in system emails.

string

required

Display name for system emails.

Integrations (SHARED)

{
  "Integrations": {
    "EncryptionKey": "<32-character-aes-key>"
  }
}

This key must be identical across all services. Losing this key makes encrypted data unrecoverable.

string

required

A 32-character AES key used to encrypt/decrypt third-party API keys stored in MongoDB (OpenAI, Twilio, ElevenLabs, etc.).Generate with:

openssl rand -base64 32

User API Keys (SHARED)

{
  "UserApiKeys": {
    "ApiKeyEncryptionKey": "<api-key-encryption-key>",
    "PayloadEncryptionKey": "<payload-encryption-key>"
  }
}

These keys must be identical across all services.

string

required

Encrypts platform API keys issued to users.Generate with:

openssl rand -base64 32

string

required

Encrypts the payload/claims within API tokens.Generate with:

openssl rand -base64 32

User

{
  "User": {
    "EmailHashPepper": "<random-string>"
  }
}

string

required

A secret string appended to email addresses before hashing for secure lookups.Generate with:

openssl rand -base64 16

Forwarded Headers

{
  "ForwardedHeaders": {
    "KnownProxies": [
      "127.0.0.1"
    ]
  }
}

array

List of trusted proxy IP addresses that define X-Forwarded-For headers (e.g., Nginx, Cloudflare).Example:

"KnownProxies": [
  "127.0.0.1",
  "10.0.0.1",
  "192.168.1.1"
]

Backend Proxy configuration

Proxy

{
  "Proxy": {
    "Id": "<server-uuid>",
    "RegionId": "us-east-1",
    "ApiKey": "<cluster-api-secret>",
    "OutboundProcessing": {
      "PollingIntervalSeconds": 5,
      "DbFetchBatchSize": 1000,
      "ProcessingBatchSize": 70,
      "ScheduleWindowMinutes": 1
    }
  }
}

string

required

Unique UUID for this Proxy instance, obtained from Admin Dashboard → Infrastructure → Servers.

string

required

Region identifier (e.g., us-east-1, eu-central) that this proxy serves.

string

required

Cluster handshake token. Must match the “API Secret” entered in the Admin Dashboard when registering this server.

integer

How often (in seconds) the proxy checks for pending outbound calls. Default: 5.

integer

Maximum number of queued calls to fetch from database per polling cycle. Default: 1000.

integer

Number of calls to process concurrently within one batch. Default: 70.

integer

Lookahead window (in minutes) for scheduled calls. Default: 1.

CORS

{
  "Cors": {
    "AllowedOrigins": [
      "https://app.iqra.bot"
    ]
  }
}

array

required

List of URLs allowed to make browser-based requests (WebRTC signaling). Include your Frontend dashboard URL.

Backend App configuration

Server

{
  "Server": {
    "Id": "<server-uuid>",
    "RegionId": "us-east-1",
    "ExpectedMaxConcurrentCalls": 25,
    "ApiKey": "<cluster-api-secret>",
    "WebhookTokenSecret": "<webhook-signing-key>"
  }
}

string

required

Unique UUID obtained from Admin Dashboard → Infrastructure → Servers.

string

required

Region identifier this server belongs to.

integer

required

Maximum number of simultaneous calls before the Proxy stops routing new traffic to this server.

string

required

Cluster handshake token matching the Admin Dashboard configuration.

string

required

Random string used to sign webhook payloads for security verification.Generate with:

openssl rand -base64 32

Hardware

{
  "Hardware": {
    "NetworkInterfaceName": "eth0",
    "MaxNetworkDownloadMbps": 200,
    "MaxNetworkUploadMbps": 50
  }
}

string

required

OS-level network interface name for RTP audio binding. See Frontend Hardware for details.

integer

Estimated download bandwidth available (used for capacity planning). Default: 200.

integer

Estimated upload bandwidth available (used for capacity planning). Default: 50.

Local Redis (Backend App only)

{
  "LocalRedisDatabase": {
    "ConnectionString": "127.0.0.1:6379",
    "TTSAudioCacheIndex": 14
  }
}

The Backend App requires a separate local Redis instance running on the same machine for L1 TTS audio caching to minimize latency.

string

required

Local Redis connection (should be 127.0.0.1 for best performance).

integer

Redis database index for TTS cache. Default: 14.

Background Processor configuration

Security

{
  "Security": {
    "ApiKey": "<api-key>"
  }
}

string

required

Cluster handshake token matching the Admin Dashboard configuration.

S3 Storage

{
  "S3Storage": {
    "DefaultStorageRegionId": "us-east-1"
  }
}

string

required

Must match the DefaultStorageRegionId in the Frontend configuration.

Shared configuration blocks

These sections must be identical across all services:

RedisDatabase

Connection to shared Redis instance

MongoDatabase

Connection to MongoDB

Milvus

Vector database configuration

Integrations

Encryption key for third-party API keys

Environment-specific configuration

Development

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*"
}

Production

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Microsoft.EntityFrameworkCore": "Warning"
    }
  },
  "AllowedHosts": "app.yourdomain.com"
}

Security best practices

Use strong encryption keys

Generate all encryption keys with openssl rand -base64 32. Never use predictable strings.

Rotate keys periodically

Plan for key rotation. Store old keys for decrypting legacy data.

Secure configuration files

Set file permissions to 600 (owner read/write only):

chmod 600 appsettings.json

Use environment variables for secrets

Override sensitive settings with environment variables:

export MongoDatabase__ConnectionString="mongodb://..."
export Integrations__EncryptionKey="..."

Never commit secrets to Git

Add appsettings.json to .gitignore. Only commit appsettings.json.example.

Configuration validation

Validate your configuration before deploying:

# Check configuration syntax
dotnet run --project ProjectIqraFrontend --configuration Release --dry-run

# Verify database connections
mongo --eval "db.adminCommand('ping')" $MONGODB_URI
redis-cli -h localhost -p 6379 ping

# Check configuration
dotnet run --project ProjectIqraFrontend --configuration Release --dry-run

# Test connections
Test-NetConnection -ComputerName localhost -Port 27017
Test-NetConnection -ComputerName localhost -Port 6379

Troubleshooting

Services can’t connect to databases

MongoDB connection failed

Symptoms: MongoConnectionException or timeout errorsSolutions:

Verify connection string format
Check MongoDB is running: sudo systemctl status mongod
Test connection: mongo mongodb://localhost:27017
Ensure firewall allows port 27017

Redis connection failed

Symptoms: RedisConnectionException or NOAUTH errorsSolutions:

Verify Redis is running: sudo systemctl status redis
Test connection: redis-cli ping
Check password if authentication is enabled
Ensure firewall allows port 6379

Milvus connection failed

Symptoms: MilvusException or timeout errorsSolutions:

Verify Milvus is running: docker ps | grep milvus
Check endpoint URL (HTTP port is usually 9091, not 19530)
Test connection: curl http://localhost:9091/health
Verify username/password if authentication is enabled

Encryption key mismatch

Symptoms: CryptographicException or “invalid padding” errors Cause: The Integrations.EncryptionKey differs between services. Solution: Ensure the exact same key is used in all four appsettings.json files.

Network interface not found

Symptoms: NetworkInterfaceNotFoundException or “No such device” Solution:

Linux: Run ip addr and use the exact interface name (e.g., eth0)
Windows: Run ipconfig and use the exact adapter name (e.g., "Ethernet")
Ensure the interface is active and has an IP address

Next steps

Self-hosting guide

Complete installation walkthrough

System requirements

Hardware and dependency specifications

​Configuration files

​Frontend configuration

​URL

​Hardware

​S3 Storage

​Redis (SHARED)

​MongoDB (SHARED)

​Milvus (SHARED)

​Unstructured

​Mail SMTP

​Integrations (SHARED)

​User API Keys (SHARED)

​User

​Forwarded Headers

​Backend Proxy configuration

​Proxy

​CORS

​Backend App configuration

​Server

​Hardware

​Local Redis (Backend App only)

​Background Processor configuration

​Security

​S3 Storage

​Shared configuration blocks

RedisDatabase

MongoDatabase

Milvus

Integrations

​Environment-specific configuration

​Development

​Production

​Security best practices

​Configuration validation

​Troubleshooting

​Services can’t connect to databases

​Encryption key mismatch

​Network interface not found

​Next steps

Self-hosting guide

System requirements

Configuration files

Frontend configuration

URL

Hardware

S3 Storage

Redis (SHARED)

MongoDB (SHARED)

Milvus (SHARED)

Unstructured

Mail SMTP

Integrations (SHARED)

User API Keys (SHARED)

User

Forwarded Headers

Backend Proxy configuration

Proxy

CORS

Backend App configuration

Server

Hardware

Local Redis (Backend App only)

Background Processor configuration

Security

S3 Storage

Shared configuration blocks

Environment-specific configuration

Development

Production

Security best practices

Configuration validation

Troubleshooting

Services can’t connect to databases

Encryption key mismatch

Network interface not found

Next steps