Multi-Tenant Setup

Overview

This document outlines the architecture, deployment strategy, configuration, and operational considerations for setting up and maintaining a multi-tenant environment for the AnswerRocket platform.

The shift from single-tenant-per-VM to multi-tenant-per-VM/container aims to optimize infrastructure efficiency while preserving tenant-level data and configuration isolation. However, you will still need to manage each tenant configuration (database, LLM, etc…) individually.

MaxAI Architecture

Single-Tenant Model

• Each client runs on a dedicated VM.
• One deployment per VM.
• Full environment isolation (URL, data, config).
• Straightforward but resource-intensive.

Multi-Tenant Model

• Single VM with container set shared by multiple tenants.
• Routing-based tenant segregation using domain or subdomain (e.g. customer1.example.com, customer2.example.com).
• Tenants configured via a JSON-based config system.

Configuration

• MongoDB: Each tenant gets its own database automatically (e.g., max_customer1, max_customer2, etc.).
• SSL Certificates: Create individual certificates per domain or use a wildcard certificate for .dev.answerrocket.com and .answerrocket.com.
• DNS: All domains point to the same VM IP or load balancer. The application routes based on the first subdomain.
• Data Isolation: Each tenant’s data is stored in its own MongoDB database within the same container.

How Subdomain Routing Works

1. Application’s Hostname Processing

1. Extracts the leading subdomain from the request hostname.
2. Looks it up in the TenantUrlOverlayMap.
3. Maps it to a tenant ID.
4. Routes to the tenant’s config and data.

2. Example TenantUrlOverlayMap

"TenantUrlOverlayMap": {
  "customer1": "customer1",
  "customer2": "customer2",
  "customer3": "customer3",
  "customer4": "customer4"
}

3. Example Routing Table

4. Subdomain-Agnostic Routing

• Only the first subdomain matters for routing.
• Example: customer1.test.answerrocket.com → routes to tenant customer1

5. Routing Flow

1. Request hits load balancer.
2. Forwarded to application VM.
3. Hostname is parsed → extract leading subdomain.
4. Subdomain maps to tenant.
5. Application loads that tenant’s config.
6. Connects to tenant’s MongoDB.
7. Serves response with tenant-specific data.

6. Verification

• Check application logs to verify tenant mapping.
• Tenant IDs must be valid subdomain strings.

SSL/TLS Considerations

• Prefer handling certificates at the Load Balancer.
• Offloading simplifies certificate and domain management.

Data Isolation & Security

• MongoDB stores are isolated per tenant.
• No cross-tenant data visibility.
• Skills, documents, and queries are tenant-scoped.

Skill Execution & Agent Isolation

• Skills and assistants (soon called agents) are scoped per tenant.
• Shared Git repos for skill codebases may be supported in the future.
• Each tenant can use common skills while maintaining independent configs.

Performance & Scaling Guidelines

Base Recommendations

Sizing Factors

• Concurrency (active users)
• Skill complexity (data processing)
• Query volume (e.g. 20k rows)
• Cache reuse/locality

📌 Memory is often the limiting factor, not CPU.

Deployment & Maintenance Considerations

Pros

• Reduced infrastructure footprint
• Easier VM management
• Centralized deployment of containers

Cons

• Single-point failure risk (misconfig affects all tenants)

Document and Skill Access Considerations

• Documents are shared within a tenant.
• No cross-tenant document visibility.

Multi-Tenant Setup Instructions (Example.com)

1. Connect to the server and switch to the max user:

sudo su max
cd /opt/answerrocket/volumes/json\_config
ls -la

2. Backup the current config:

cp /opt/answerrocket/volumes/json_config/system_config.json /opt/answerrocket/volumes/json_config/system_config.json.bak

3. Update system_config.json:

"TenantList": ["customer1", "customer2", "customer3", "customer4"],
...
"TenantUrlOverlayMap": {
    "customer1": "customer1",
    "customer2": "customer2",
    "customer3": "customer3",
    "customer4": "customer4"
}

4. Create tenant directories:

mkdir -p customer1 customer2 customer3 customer4
cp example/* customer1/
cp example/* customer2/
cp example/* customer3/
cp example/* customer4/

5. Update configs per tenant

sed -i 's/example/customer1/g' customer1/*
sed -i 's/example/customer2/g' customer2/*
sed -i 's/example/customer3/g' customer3/*
sed -i 's/example/customer4/g' customer4/*

6. Restart the app using internal-compose.sh if SSL cert on load balancer OR prod-compose.sh if SSL cert on server:

cd /opt/answerrocket

# If SSL on Load Balancer
./scripts/internal-compose.sh down
./scripts/internal-compose.sh up -d

# If SSL on server
./scripts/prod-compose.sh down
./scripts/prod-compose.sh up -d

6. DNS Setup (e.g. AWS Route53):

Create CNAME or A records pointing to the server IP or Load Balancer like so given the example above:

• customer1.dev.example.com → alb.example.com
• customer2.dev.example.com → alb.example.com
• customer3.example.com → alb.example.com
• customer4.example.com → alb.example.com

Database Configuration

Databases in the mongodb container will automatically be created for each tenant on application startup or restart based on whats configured in you system_config.json.