MaxAI Installation Guide

Provision Server

Provision a server in your environment following this documentation:

https://help.answerrocket.com/docs/self-hosting-requirements#/

Setup User

SSH to your server and run the following commands to create a dedicated answerrocket user and directory.

sudo useradd -m -s /bin/bash max
sudo usermod -aG docker max
sudo mkdir -p /opt/answerrocket
sudo chown -R max:max /opt/answerrocket
sudo usermod -aG docker 
sudo su max

Setup Access Credentials

Our infrastructure team will need to provide you with aws cli credentials to pull the MaxAI images and docker configs.

Configure them on the VM with: aws configure:

• Enter the keys provided when prompted.
• Region: us-east-1

Pull Application

Run the following commands to pull the latest

cd /opt/answerrocket
aws s3 cp s3://aglabs-deployment/docker-full-install/docker-installation-bundle-v{version}.tar .
tar -xvf docker-installation-bundle-{version}.tar

# go back to root user for the following commands
exit
sudo chown -R max:max /opt/answerrocket
sudo chmod +x /opt/answerrocket

# now become the max user again to configure the application settings
sudo su max

Config File

Now we must edit the MaxAI configuration to specify your Tenant name and domain. Edit the /opt/answerrocket/volumes/json_config/system_config.json file.

Specifically you must edit these fields, replacing xxxx with your tenant name and yyyy with your subdomain:

• TenantList: Usually just your company name, although you can give the application a custom name.
• TenantUrlOverlayMap: This maps the Tenant from the TenantList to the leading subdomain you will point to the server. ONLY the leading (first) subdomain matters here, not the full domain.
• BaseUrl: This is the full URL including subdomain you will be pointing to the server.

"MaxConfig" : {
        "OverlayName" : "ricedemo",
        "MultiTenant" : true,
        "TenantList" : ["xxxx"],
        "UseSSL": false,
        "SelectLimitDefault": 10000,
        "UseCache": true,
        "IsDebugMode": false,
        "UseNode": true,
        "EnableScheduleFailureTickets": false,
        "JavaServerHostname": "maxappserver",
        "JavaFrontendServerPort": 8182,
        "ExternallyManagedSkillWorkers": false,
        "WorkerPoolSize": 5,
        "JavaAppServerUrl": "http://maxappserver:8183",
        "NodeServerHostname": "node",
        "NodeServerPort": 4001,
        "RunDataPipelineServices": true,
        "IsTaskEngineEnabled": true,
        "RunSecondaryWebServices": true,
        "EnableInsightEditor": false,
        "EnablePendo": false,
        "TenantUrlOverlayMap": {
          "yyyy": "xxxx"
        }
    },
    "MaxServerConfig" : {
        "LocalMongoBinPath": "/usr/bin/",
        "CentralMongoConnect" : "mongodb://mongod:27017/",
        "CentralMongoDB" : "max",
        "CentralMongoPrefix" : "max_",
        "SendSystemMetrics": false,
        "EnterpriseMongoMap" : {
            "example enterprise name" : "mongodb://example server name:27017",
            "*" : "mongodb://localhost:27017/"
        },
        "BaseUrl": "yyyy.example.com",
        "UseChromeForRendering": false
    },
    "AnswerRocketServerConfig" : {
        "test" : "zzz",
        "url" : "http://background.dev.answerrocket.com:8080/AnswerRocketWebServices"
    },

Examples

URL: xxx-yyy.testcorp.com:

        "TenantList" : ["testcorp"],
...        
      "TenantUrlOverlayMap": {
          "xxx-yyy": "testcorp"
        }
...
        "BaseUrl": "xxx-yyy.testcorp.com",

URL: xxx.yyy.testcorp.com:

        "TenantList" : ["testcorp"],
...        
      "TenantUrlOverlayMap": {
          "xxx": "testcorp"
        }
...
        "BaseUrl": "xxx.yyy.testcorp.com",

Authenticate with AWS CLI

Run this script to to authenticate with aws cli:

cd /opt/answerrocket
./scripts/aws-cli-registry-auth.sh

Build the MaxAI Application

You can now build the MaxAI application.

Depending on where you plan to host your SSL Certificates you must run either the prod-compose.sh or internal-compose.sh script. (SSL Certificate instructions to follow)

If using self-provisioned SSL Certs placed in the VM:

cd /opt/answerrocket
./scripts/prod-compose.sh up -d

If using a Load Balancer to manage SSL Certs:

cd /opt/answerrocket
./scripts/internal-compose.sh up -d

Setup DNS Record

Setup DNS record and point it to the VM IP address or your load balancer. Make sure it matches the configuration file you edited above.

SSL Certificate

If managing SSL certificates outside of a load balancer, follow the instructions below. Otherwise you can skip this step.

Option 1: Certbot & Lets Encrypt

Run the following commands replacing the domains with your domains:

# Update package list
sudo apt-get update
 
# Install certbot
sudo apt-get install certbot
 
# Navigate to the application directory
cd /opt/answerrocket
 
# Connect to aws (if not already done)
./scripts/aws-cli-registry-auth.sh
 
# Request a new certificate
sudo certbot certonly --manual --preferred-challenges dns -d "*.dev.example.com" -d "dev.example.com"
 
# Copy certificates to nginx directory
sudo cp /etc/letsencrypt/live/dev.answerrocket.com/fullchain.pem ./volumes/certs/fullchain.pem
sudo cp /etc/letsencrypt/live/dev.answerrocket.com/privkey.pem ./volumes/certs/privkey.pem
 
# Reload nginx
docker exec ar-nginx-1 nginx -s reload

Option 2: Custom Self-Generated Cert

Generate a fullchain.pem and privkey.pem and place them here:

/opt/answerrocket/volumes/certs/fullchain.pem
/opt/answerrocket/volumes/certs/privkey.pem

Create this file /opt/answerrocket/volumes/certs/certificates.conf

# To enable SSL. Verify certificate location.
listen 443 ssl http2;
ssl_certificate /etc/nginx/certs/fullchain.pem;
ssl_certificate_key /etc/nginx/certs/privkey.pem;

Create User

Run this script, setting the TENANT=<tenant_name> variable to the tenant name in your system_config.json TenantList.

This will create an admin user with the following credentials:

• Username: admin
• Password: hello

docker exec -e TENANT=<tenant_name> ar-webhost-1 python -c "
import hashlib, pymongo, os
from uuid import uuid4

def client_salted_pwd_hash(password):
    return hashlib.sha256((password + '7c6834b742044644b91e5eaad8fba08f').encode('utf-8')).hexdigest()

def server_salted_hash_pwd(client_hashed_password):
    salt = os.urandom(24).hex()
    return hashlib.sha256((client_hashed_password + salt).encode('utf-8')).hexdigest() + '|' + salt

try:
    tenant = os.environ.get('TENANT', 'auglytix')
    client = pymongo.MongoClient(host='mongodb', port=27017, tz_aware=True, uuidRepresentation='standard')
    
    # Check if tenant database exists
    existing_dbs = client.list_database_names()
    if tenant not in existing_dbs:
        print(f'❌ Error: Tenant \"{tenant}\" does not exist.')
        print(f'Available tenants: {[db for db in existing_dbs if db not in [\"admin\", \"config\", \"local\"]]}')
        exit(1)
    
    db = client[tenant]
    
    # Check if users collection exists
    if 'users' not in db.list_collection_names():
        print(f'❌ Error: Tenant \"{tenant}\" exists but has no users collection.')
        print('This tenant may not be properly initialized.')
        exit(1)
    
    existing_user = db.users.find_one({'login_name': 'admin'})
    if existing_user:
        print(f'⚠️  Admin user already exists in tenant \"{tenant}\"!')
    else:
        admin_user = {
            '_id': uuid4(),
            'profile': {'family_name': 'AnswerRocket', 'email_address': '[email protected]', 'given_name': 'Admin'},
            'rights': {'admin': True, 'semantic_admin': True, 'scheduling': True},
            'pwd_hash': server_salted_hash_pwd(client_salted_pwd_hash('hello')),
            'login_name': 'admin'
        }
        db.users.insert_one(admin_user)
        print(f'✅ Admin user created in tenant: \"{tenant}\"')
        print('   Username: admin, Password: hello')
        
except pymongo.errors.ServerSelectionTimeoutError:
    print('❌ Error: Cannot connect to MongoDB. Check if containers are running.')
except Exception as e:
    print(f'❌ Error: {str(e)}')
"

We recommend you only use this as a temporary user to login and create your admin users with your emails and/or setup SSO, then delete it.

Access MaxAI

You can now access your MaxAI application from the domain you setup with the credentials above.