Self-hosting guide

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 interface
Backend Proxy - Load balancer and SIP gateway
Backend App - Core agent engine handling calls
Background Processor - Async tasks and analytics

Prerequisites

Before beginning installation, ensure you have:

System requirements

Review the system requirements for hardware specifications and supported operating systems.

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.

6. Configure S3 storage

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"

7. Configure the applications

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:

Linux
Windows

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 regions
Use a reverse proxy (Nginx, Caddy) in front of the Frontend
Configure MongoDB replica sets for database redundancy
Use Redis Cluster instead of standalone Redis
Deploy 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

​Pre-release notice

​Architecture overview

​Service roles

​Prerequisites

​Installation steps

​1. Clone the repository

​2. Install .NET 10 Runtime

​3. Set up MongoDB

​4. Install Redis

​5. Deploy Milvus vector database

​6. Configure S3 storage

​7. Configure the applications

​8. Generate encryption keys

​9. Determine network interface name

​10. Build the applications

​11. Initialize the database

​12. Start the services

​Production deployment

​Using systemd (Linux)

​Using Docker Compose

​Load balancing and high availability

​Monitoring and maintenance

​Health checks

​Log management

​Backup strategy

​Troubleshooting

​Services fail to start

​Audio quality issues

​High memory usage

​Updating

​Next steps

Configuration reference

System requirements

Security best practices

Contributing

Pre-release notice

Architecture overview

Service roles

Prerequisites

Installation steps

1. Clone the repository

2. Install .NET 10 Runtime

3. Set up MongoDB

4. Install Redis

5. Deploy Milvus vector database

6. Configure S3 storage

7. Configure the applications

8. Generate encryption keys

9. Determine network interface name

10. Build the applications

11. Initialize the database

12. Start the services

Production deployment

Using systemd (Linux)

Using Docker Compose

Load balancing and high availability

Monitoring and maintenance

Health checks

Log management

Backup strategy

Troubleshooting

Services fail to start

Audio quality issues

High memory usage

Updating

Next steps