Skip to content

Admin Guide for InspectRAG 🛠️

About this Guide

This guide provides system administrators with step-by-step instructions to install, configure, and manage InspectRAG. It includes detailed installation guides for both Linux and Windows platforms, instructions on OpenID integration, LDAP configuration, SharePoint setup, real-time synchronization, and the use of environment variables for smooth deployment. Additionally, it covers the configuration of the docker-compose.yml file required for deployment, with necessary modifications for pulling Docker images.

Table of Contents

  1. Installation Guide
  2. Prerequisites
  3. Installation Steps
  4. System Setup
  5. Step 1: Install and Configure OpenID Provider
  6. Step 2: Integrate with Active Directory via LDAP
  7. Step 3: Set Up VectorDB
  8. Step 4: Configure SharePoint Integration
  9. Managing Users and Permissions
  10. Environment Variables Configuration
  11. System Monitoring and Logs
  12. Troubleshooting Common Issues
  13. Best Practices for Administrators

Installation Guide

This guide explains how to install and set up InspectRAG using the zip file with Docker and Docker Compose.

Prerequisites

Before proceeding, ensure you have requested your Docker Hub Personal Access Token (PAT) from [email protected]. The PAT is required for Docker Hub authentication during the installation and you have at least 30 GBs of freee space.

Installation Steps

Step 1: Extract the Package File

Extract the provided package that includes docker-compose.yml, InspectRAG-CLI,files into a directory.

Step 2: Run the Install Script

Execute the installation script by running the following command:

./InspectRAG-CLI -p /full/path/to/InspectRAG-CLI -o install

Important Notes: The installer script is designed for Linux systems only - The installer should only be used for initial installation - After installation, use standard Docker Compose commands for daily operations - The -p flag must point to the full path where you extracted the files

Environment Configuration: - By default, the installer will prompt you for various configuration values during installation - To bypass interactive configuration, you can use the --env-file parameter:

./InspectRAG-CLI -p /full/path/to/InspectRAG-CLI -o install --env-file /path/to/env.file

What the Install Script Does

  1. Check for Docker: The script checks if Docker is installed. If not, it installs Docker along with necessary dependencies.
  2. Check for Docker Compose: Similarly, it checks for Docker Compose and installs it if it’s missing.
  3. Prompt for Docker Hub PAT: During execution, the script will request:
  4. Your Docker Hub username.
  5. The PAT token provided by [email protected].
  6. Authenticate with Docker Hub: The script validates the PAT token and authenticates with Docker Hub.
  7. Environment Variable Configuration: It will prompt you to input or confirm key environment variables:
  8. RAG_PORT
  9. POSTGRES_USER
  10. POSTGRES_PASSWORD
  11. SHAREPOINT_HOSTNAME, SHAREPOINT_SITE_PATH
  12. RAG_OPENAI_API_KEY, OPENAI_API_KEY
  13. GRAPH_API_CLIENT_ID, GRAPH_API_CLIENT_SECRET, GRAPH_API_TENANT_ID
  14. CHUNK_SIZE (default: 1500)
  15. CHUNK_SCORE_THRESHOLD (default: 0.5)
  16. Validate docker-compose.yml Configuration: It ensures you’ve correctly configured docker-compose.yml to use the provided environment variables. You’ll be asked to confirm this step.
  17. Pull Required Docker Images: The script pulls these images from Docker Hub:
  18. eunomatix/inspect-rag-api
  19. eunomatix/inspect-rag:-celery
  20. ankane/pgvector:latest
  21. Start Docker Compose: All services are launched using docker compose up -d.

Post-Installation Steps

Step 3: Verify Installation

  1. Check Container Status: 
    docker-compose ps

Ensure all services are running.

  1. Check Logs: 
    docker-compose logs -f

Review logs for any errors during startup.

Additional Notes

  • Ensure your environment variables match the requirements of your deployment.
  • If the script encounters issues, check that docker-compose.yml exists and is correctly configured.
  • For further assistance, contact [email protected].
  • To setup Sharepoint Online/Onprem you can check their guide on Online Guide/OnPrem Guide

2. System Setup

Prerequisites

Ensure the following prerequisites are met:

  • Active Directory (AD) is configured for managing users and roles.
  • OpenID provider (e.g., Keycloak or Azure AD) is installed and accessible.
  • VectorDB is installed to store embeddings and query data.
  • SharePoint Online or On-Prem is available with the required permissions.

Step 1: Install and Configure OpenID Provider

  1. Set Up OpenID Provider:

  2. Install and configure your OpenID Provider (e.g., Keycloak or Azure AD) to handle authentication.

  3. Enable LDAP Integration:

  4. Integrate LDAP with your OpenID provider to import users and roles from AD.

  5. Configure OpenID Clients for InspectRAG:

  6. Specify the callback URI for InspectRAG.

  7. Generate and securely store the client ID and secret.

Step 2: Integrate with Active Directory via LDAP

  1. Configure LDAP Settings:

  2. Connect to the AD server using the LDAP protocol.

  3. Provide the bind DN and password for querying the AD server.

  4. For further details you can refer to the LDAP Configuration Guide

  5. Synchronize Users and Roles:

  6. Import users and groups from AD into the OpenID provider.

  7. Ensure hierarchical roles are correctly mapped.

Step 3: Set Up VectorDB

  1. Install VectorDB:

  2. Use Docker or your preferred setup to install VectorDB.

  3. Initialize the Database:

  4. Create schemas to store embeddings and metadata.

  5. Connect InspectRAG to the Database:

  6. Provide the database connection details in the .env file.

Step 4: Configure SharePoint Integration

For SharePoint Online:

  1. Register an App in Azure AD:

  2. Register a new application for Microsoft Graph API access.

  3. Grant API Permissions:

  4. Add permissions: Sites.Read.All, Sites.Manage.All.

  5. Set Up Webhooks:

  6. Configure webhooks to receive real-time file change notifications.

For SharePoint On-Prem:

  1. Deploy Event Receivers:

  2. Use PowerShell scripts to deploy event receivers.

  3. Enable InspectRAG Plugin:

  4. Install and enable the InspectRAG plugin.

  5. Verify LDAP Integration:

  6. Ensure roles and permissions sync between AD and SharePoint.

3. Managing Users and Permissions

Role Management in OpenID

  • Sync Roles and Groups:

  • Ensure roles and groups from AD are synced with the OpenID provider.

  • Map Roles to SharePoint Permissions:

  • Align roles with permissions in SharePoint.

  • Assign Roles Appropriately:

  • Assign roles based on departments or group membership.

Configuring SharePoint Permissions

  • Set Document-Level Permissions:

  • Assign permissions at the document level.

  • Align with AD Roles:

  • Ensure permissions correspond to user roles from AD.

Monitoring Synchronization

  • Utilize Webhooks and Event Receivers:

  • Capture file changes and role updates in real-time.

  • Immediate Reflection of Changes:

  • Ensure role changes in AD are promptly updated.

4. Environment Variables Configuration

Ensure the following environment variables are configured correctly in your .env file.

# OpenAI API Keys
RAG_OPENAI_API_KEY=sk-your-openai-key
OPENAI_API_KEY=sk-another-openai-key

# PostgreSQL Database Configuration
POSTGRES_DB=inspectrag_db
POSTGRES_USER=inspectrag_user
POSTGRES_PASSWORD=password123
DB_HOST=vectordb
DB_PORT=5432

# MongoDB Configuration (if needed)
COLLECTION_NAME=inspectrag_collection
ATLAS_MONGO_DB_URI=mongodb://username:password@host:port/dbname

# Microsoft Graph API Configuration
GRAPH_API_CLIENT_ID=your-client-id
GRAPH_API_CLIENT_SECRET=your-client-secret
GRAPH_API_TENANT_ID=your-tenant-id

# SharePoint Configuration
SHAREPOINT_HOSTNAME=yourcompany.sharepoint.com
SHAREPOINT_SITE_PATH=/sites/UsersSite
SHAREPOINT_ENABLED=true

# Redis Configuration
RAG_REDIS_URL=redis://inspectrag-redis:6379/0

# Document Processing Configuration
CHUNK_SIZE=1500
CHUNK_SCORE_THRESHOLD=0.5

Variable Descriptions

  • CHUNK_SIZE:

  • Defines the maximum character length for each document chunk processed by the embedding model.

  • Implications:
    • Larger Values: Fewer chunks with more context per chunk.
    • Smaller Values: More chunks with less context per chunk.

  • Recommendation: Adjust based on document sizes and desired granularity.

  • CHUNK_SCORE_THRESHOLD:

  • Sets the minimum cosine similarity score threshold for retrieving relevant chunks in response to queries.

  • Cosine Similarity:
    • Measures the similarity between two vectors.
    • Ranges from -1 (exact opposite) to 1 (exactly the same).
  • Interpretation:
    • Lower Threshold Values: Stricter matching; only highly similar chunks are retrieved.
    • Higher Threshold Values: Looser matching; more chunks are retrieved, including less similar ones.
    • This is done in order to prevent unrelated chunks of personal data to go to your LLM model as part of query.

Chunk Score Threshold Table

Threshold Value Strictness Level Description
0.1 Very High Only the most similar chunks are retrieved.
0.3 High Retrieves chunks with strong similarity to the query.
0.5 Moderate Balances precision and recall.
0.7 Low Retrieves more chunks, including moderately similar ones.
0.9 Very Low Retrieves most chunks, even if similarity is low.

Note: Adjust CHUNK_SCORE_THRESHOLD based on your application's need for precision (fewer, more relevant chunks) versus recall (more chunks, potentially less relevant).

5. System Monitoring and Logs

Enable Audit Logs

  • Capture Activities:

  • Record all access attempts, queries, and modifications.

  • Secure Log Storage:

  • Ensure logs are stored securely and accessible only to authorized personnel.

Monitor Alerts

  • Set Up Alerts for Suspicious Activities:

  • Configure alerts for failed login attempts and unauthorized access.

  • Proactive Threat Response:

  • Use alerts to respond quickly to potential security threats.

Regular Log Review

  • Periodic Analysis:

  • Regularly review logs to identify patterns or anomalies.

  • Compliance and Reporting:

  • Maintain logs for compliance purposes and generate reports as required.

6. Troubleshooting Common Issues

Issue 1: Users Not Syncing from AD to OpenID

Solution:

  • Verify LDAP Configuration:

  • Ensure LDAP settings in the OpenID provider are correct.

  • Check Network Connectivity:

  • Confirm network connectivity between the OpenID provider and the AD server.

  • Validate Bind Credentials:

  • Ensure the bind DN and password are correct and have necessary permissions.

Issue 2: Incorrect User Access Permissions

Solution:

  • Review SharePoint Permissions:

  • Check that SharePoint permissions align with roles from AD.

  • Manual Sync:

  • Perform a manual sync of users and roles between AD and the OpenID provider.

Issue 3: Webhooks Not Working in SharePoint Online

Solution:

  • Verify Microsoft Graph API Permissions:

  • Ensure the app has the necessary permissions.

  • Check Notification URL Accessibility:

  • Confirm that the webhook notification URL is correctly configured and accessible.

7. Best Practices for Administrators

  • Periodic Sync of AD Roles:

  • Schedule regular synchronization to keep roles and permissions up to date.

  • Audit User Activity:

  • Regularly monitor user activities to detect unauthorized access.

  • Test Permissions Regularly:

  • Conduct periodic tests to ensure permissions are correctly enforced.

  • Monitor Webhooks and Event Receivers:

  • Ensure that file changes are captured and processed in real-time.

  • Backup Configurations and Data:

  • Maintain regular backups to prevent data loss.

  • Stay Updated:

  • Keep all components, including Docker images and dependencies, updated to the latest stable versions.

8. Making a Query Request to InspectRAG

This section outlines how to: 1. Obtain an access token from your OpenID provider. 2. Use the access token in a Chat Completions API request to query InspectRAG.

Step 1: Obtaining the Access Token

To authenticate requests, you'll need a JWT access token from an OpenID provider. This token is required to contain specific fields for authorization in InspectRAG.

JWT Token Requirements

The token must be a JSON Web Token (JWT) with fields similar to the following example:

{
  "exp": 1731259764,
  "iat": 1731259464,
  "jti": "90bd5c93-0f4d-429b-8536-df475b23a77e",
  "iss": "https://your-openid-provider.com/realms/YourRealm",
  "sub": "926e6a63-8c7e-40a9-96cb-b764362e932e",
  "typ": "Bearer",
  "azp": "your-client-id",
  "allowed-origins": [
    "https://your-app-domain.com"
  ],
  "realm_access": {
    "roles": [
      "default-roles-inspectchat",
      "Members",
      "offline_access",
      "uma_authorization"
    ]
  },
  "scope": "profile email",
  "name": "janedoe",
  "preferred_username": "janedoe",
  "email": "[email protected]"
}

Key Fields in the Token: - exp and iat: Expiration and issued-at timestamps. - iss: The issuer URL (your OpenID provider). - sub: User's unique ID. - azp: Client ID used to request the token. - realm_access.roles: Array of roles assigned to the user, such as "Members" or the roles user must have to query the file. - preferred_username: Username for identifying the user. - email: User's email address.

Getting the Token (Example)

Here's an example curl command to obtain the token from an OpenID provider:

curl -X POST "https://your-openid-provider.com/realms/YourRealm/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=your-client-id" \
  -d "client_secret=your-client-secret" \
  -d "grant_type=password" \
  -d "username=janedoe" \
  -d "password=your-password"

This command will return a JSON response containing the access token under "access_token".

Step 2: Using the Access Token in Chat Completions

After obtaining the access token from your OpenID provider, use it in the Chat Completions API request as shown below.

Example Chat Completions Request

curl -X POST "http://RAG_API_URL/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-user-name: janedoe" \
  -H "accesstoken: YOUR_ACCESS_TOKEN" \
  -d '{
        "model": "gpt-4",
        "temperature": 1,
        "top_p": 1,
        "presence_penalty": 0,
        "frequency_penalty": 0,
        "user": "user-unique-id",
        "stream": true,
        "messages": [
          {
            "role": "user",
            "content": "Your question here"
          }
        ]
      }'

Explanation of Headers and Body Fields

  • Headers:
  • Authorization: Bearer YOUR_ACCESS_TOKEN: Used to authenticate the request, where YOUR_ACCESS_TOKEN is the JWT token obtained from your OpenID provider.
  • Content-Type: application/json: Specifies that the request body is in JSON format.
  • x-user-name: janedoe: The username or preferred_username from the token, typically used for tracking or logging purposes.

  • accesstoken: YOUR_ACCESS_TOKEN: Provides the same access token for additional validation by the API.

  • Body Fields:

  • "model": "gpt-4": Specifies the model to use for the response generation.
  • "temperature", "top_p", "presence_penalty", "frequency_penalty": Control settings for response creativity, randomness, and variety.
  • "user": "user-unique-id": Replace with a unique identifier for the user (e.g., the sub field from the JWT token).
  • "messages":
    • "role": "user": Sets the role for the message, indicating it’s a user-initiated query.
    • "content": "Your question here": Replace with the question or query content you want to submit to the Chat Completions API.