Self-hosting gives you complete control over the Iqra AI infrastructure, allowing you to run the core agent engine on your own servers while managing all dependencies and configuration.
The self-hosted version excludes the commercial multi-tenant billing and whitelabeling modules. These features are only available in Iqra Cloud.
Pre-release notice Version 0.1 Pending - The codebase is currently active but requires manual service configuration. Automated database seeding scripts will be included in the official v0.1 release. Production deployment currently requires manual database setup.
Architecture overview Iqra AI consists of four main services:
Service roles
Frontend - Admin dashboard and API interfaceBackend Proxy - Load balancer and SIP gatewayBackend App - Core agent engine handling callsBackground Processor - Async tasks and analytics
Prerequisites Before beginning installation, ensure you have:
Install dependencies
Install all required services:
.NET 10 Runtime
MongoDB (replica set recommended)
Redis (cluster mode for production)
Milvus vector database
S3-compatible storage (RustFS or AWS S3)
Network configuration
Configure firewall rules and network interfaces for RTP audio (UDP) and signaling.
Installation steps 1. Clone the repository git clone https://github.com/abdofallah/IqraAI.git cd IqraAI
2. Install .NET 10 Runtime Ubuntu/Debian
CentOS/RHEL
Windows
wget https://dot.net/v1/dotnet-install.sh chmod +x dotnet-install.sh ./dotnet-install.sh --channel 10.0 --runtime aspnetcore
sudo dnf install dotnet-runtime-10.0
3. Set up MongoDB Iqra AI requires MongoDB for metadata storage:
# Install MongoDB curl -fsSL https://www.mongodb.org/static/pgp/server-7.0.asc | \ sudo gpg -o /usr/share/keyrings/mongodb-server-7.0.gpg --dearmor echo "deb [ signed-by=/usr/share/keyrings/mongodb-server-7.0.gpg ] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/7.0 multiverse" | \ sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list sudo apt-get update sudo apt-get install -y mongodb-org # Start MongoDB sudo systemctl start mongod sudo systemctl enable mongod
For production deployments, configure MongoDB as a replica set for high availability and to support transactions.
4. Install Redis # Install Redis sudo apt-get install redis-server # Configure Redis for production sudo nano /etc/redis/redis.conf # Set: maxmemory 2gb # Set: maxmemory-policy allkeys-lru # Start Redis sudo systemctl start redis-server sudo systemctl enable redis-server
5. Deploy Milvus vector database Milvus is required for RAG (Retrieval-Augmented Generation) and knowledge base features:
# Download Milvus standalone wget https://github.com/milvus-io/milvus/releases/download/v2.4.0/milvus-standalone-docker-compose.yml -O docker-compose.yml # Start Milvus docker-compose up -d
Milvus will be available at http://localhost:19530.
RustFS (Recommended)
AWS S3
MinIO
Deploy the RustFS S3-compatible server: # Clone RustFS git clone https://github.com/rustfs/rustfs.git cd rustfs # Build and run cargo build --release ./target/release/rustfs --data-dir /var/lib/rustfs
Create an S3 bucket and IAM user with appropriate permissions: { "Version" : "2012-10-17" , "Statement" : [ { "Effect" : "Allow" , "Action" : [ "s3:*" ], "Resource" : [ "arn:aws:s3:::your-bucket-name/*" ] } ] }
docker run -p 9000:9000 -p 9001:9001 \ -e MINIO_ROOT_USER=admin \ -e MINIO_ROOT_PASSWORD=password \ minio/minio server /data --console-address ":9001"
Copy and configure the settings for each service:
Frontend configuration
cd ProjectIqraFrontend cp appsettings.json.example appsettings.json nano appsettings.json
See the configuration reference for all available options.
Backend Proxy configuration
cd ProjectIqraBackendProxy cp appsettings.json.example appsettings.json nano appsettings.json
Configure the server ID, region, and API key from the admin dashboard.
Backend App configuration
cd ProjectIqraBackendApp cp appsettings.json.example appsettings.json nano appsettings.json
Set the network interface name for RTP audio binding.
Background Processor configuration
cd IqraBackgroundProcessor cp appsettings.json.example appsettings.json nano appsettings.json
Configure MongoDB and Milvus connections. 8. Generate encryption keys All services require shared encryption keys for security:
# Generate a 32-character AES key for integrations openssl rand -base64 32 # Generate API key encryption keys openssl rand -base64 32 # ApiKeyEncryptionKey openssl rand -base64 32 # PayloadEncryptionKey # Generate email hash pepper openssl rand -base64 16 # Generate webhook token secret openssl rand -base64 32
Store these keys securely. Losing encryption keys will make existing data unrecoverable. The Integrations.EncryptionKey MUST be identical across all four services.
9. Determine network interface name The Backend App and Proxy require the OS-level network interface name for RTP audio:
ip addr # Look for the interface with your server's IP (e.g., eth0, ens5)
ipconfig # Note the adapter name (e.g., "Ethernet", "vEthernet (WSL)")
Update the Hardware.NetworkInterfaceName setting in all configuration files.
10. Build the applications # Build all projects dotnet build ProjectIqra.sln --configuration Release
11. Initialize the database Automated seeding scripts will be included in v0.1. For now, manual database initialization is required.
Connect to MongoDB and create the required collections and indexes manually, or wait for the v0.1 release with automated setup.
12. Start the services Start each service in order:
# Start Frontend cd ProjectIqraFrontend dotnet run --configuration Release # Start Backend Proxy (in new terminal) cd ProjectIqraBackendProxy dotnet run --configuration Release # Start Backend App (in new terminal) cd ProjectIqraBackendApp dotnet run --configuration Release # Start Background Processor (in new terminal) cd IqraBackgroundProcessor dotnet run --configuration Release
For production deployments, use a process manager like systemd (Linux) or create Windows Services to ensure services restart automatically.
Production deployment Using systemd (Linux) Create service files for each component:
# /etc/systemd/system/iqra-frontend.service [Unit] Description =Iqra AI Frontend After =network.target [Service] Type =simple User =iqra WorkingDirectory =/opt/iqra/ProjectIqraFrontend ExecStart =/usr/bin/dotnet /opt/iqra/ProjectIqraFrontend/bin/Release/net10.0/ProjectIqraFrontend.dll Restart =always RestartSec =10 Environment = ASPNETCORE_ENVIRONMENT =Production [Install] WantedBy =multi-user.target
Enable and start the services:
sudo systemctl enable iqra-frontend iqra-proxy iqra-backend iqra-processor sudo systemctl start iqra-frontend iqra-proxy iqra-backend iqra-processor
Using Docker Compose Official Docker images will be available with the v0.1 release. For now, build custom images from the source.
Load balancing and high availability For production deployments:
Deploy multiple Backend App instances across different regionsUse a reverse proxy (Nginx, Caddy) in front of the FrontendConfigure MongoDB replica sets for database redundancyUse Redis Cluster instead of standalone RedisDeploy Milvus in distributed mode for large-scale vector operations
Monitoring and maintenance Health checks Each service exposes health check endpoints:
Frontend: http://localhost:5000/health
Backend Proxy: http://localhost:5001/health
Backend App: http://localhost:5002/health
Background Processor: http://localhost:5003/health
Log management Configure logging in appsettings.json:
{ "Logging" : { "LogLevel" : { "Default" : "Information" , "Microsoft.AspNetCore" : "Warning" } } }
For production, integrate with centralized logging:
ELK Stack (Elasticsearch, Logstash, Kibana)Grafana Loki Datadog CloudWatch (AWS)
Backup strategy
MongoDB backups
# Daily automated backups mongodump --uri= "mongodb://localhost:27017" --out=/backups/$( date +%Y%m%d )
Redis persistence
Enable RDB snapshots and AOF in redis.conf: save 900 1 appendonly yes
S3 versioning
Enable versioning on your S3 bucket to prevent accidental deletions.
Configuration backup
Version control all appsettings.json files (excluding secrets) in a private repository.
Troubleshooting Services fail to start Check the logs for errors:
journalctl -u iqra-frontend -n 50
Common issues:
Incorrect database connection strings
Missing encryption keys
Network interface name mismatch
Port conflicts
Audio quality issues RTP audio problems are often related to:
Incorrect network interface configuration
Firewall blocking UDP traffic
Insufficient bandwidth allocation
Network jitter or packet loss
High memory usage Optimize Redis and Milvus memory:
# Limit Redis memory redis-cli CONFIG SET maxmemory 2gb # Adjust Milvus cache size in milvus.yaml
Updating To update to a new version:
# Pull latest changes git pull origin main # Rebuild applications dotnet build ProjectIqra.sln --configuration Release # Restart services sudo systemctl restart iqra- *
Always backup your database before updating. Review the changelog for breaking changes and migration steps.
Next steps
Configuration reference Detailed documentation for all configuration options
System requirements Hardware sizing and capacity planning guidance
Security best practices Harden your self-hosted deployment
Contributing Contribute to the open-source project