> ## Documentation Index
> Fetch the complete documentation index at: https://prismeai-legacy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Products Installation Prerequisites

> All the prerequisites and configuration steps needed before installing Prisme.ai AI Products

Before initializing Prisme.ai AI Products, you need to ensure that your environment meets [all necessary prerequisites](/self-hosting/requirements) and configurations. This guide will walk you through the required services, configuration steps, and verification processes.

## Requirements

### Services running

A fully operational Prisme.ai environment is required, including both open-source and private microservices.

<Tabs>
  <Tab title="Core namespace">
    The following microservices must be running:

    * `prismeai-api-gateway`
    * `prismeai-console`
    * `prismeai-pages`
    * `prismeai-workspaces`
    * `prismeai-events`
    * `prismeai-runtime`
  </Tab>

  <Tab title="Apps namespace">
    The following Apps microservices must be available:

    * `prismeai-functions`: Executes JavaScript or Python code generated by LLMs or crafted by developers, enabling powerful custom automation.
    * `prismeai-crawler`: Web document indexing
    * `prismeai-searchengine`: Search engine
  </Tab>
</Tabs>

### Offline environments

If the installation environment does not have access to internet, ensure that the following prerequisites are always met :

* If using app microservices, prismeai-functions need access to a NPM registry. If the default [https://registry.npmjs.org/](https://registry.npmjs.org/) is not available, you must configure your own npm registry using NPM\_CONFIG\_REGISTRY environment variable inside prismeai-functions microservice
  * Depending on your NPM proxy, it might require additional configuration for authentication
* If using internal / self-signed TLS certificates, they must be configured inside almost all microservices to avoid HTTPS errors
  * prismeai-searchengine and prismeai-crawler are Python microservices : once mounted, the certificate file location can be configured with REQUESTS\_CA\_BUNDLE
    prismeai-llm does not need the custom certificate
  * Every other prismeai-\* services are NodeJS : once mounted, the certificate file location can be configured with NODE\_EXTRA\_CA\_CERTS

### Platform Readiness

Before proceeding with the AI Products installation, verify that the platform is healthy using the [Readiness API](/self-hosting/operations/testing#platform-readiness-api). All core services must report a `ready` status:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_TOKEN" https://api.your-domain.com/v2/readiness
```

You can directly open this url from a browser already authenticated as super admin.

The response should return `"status": "ready"` for all services. If any service reports errors, resolve them before continuing with the installation.

### Hardware

<CardGroup cols="2">
  <Card title="Minimum Requirements" icon="server">
    * 8 CPU cores
    * 16GB RAM
    * 100GB storage
    * Suitable for testing and small-scale deployments
  </Card>

  <Card title="Recommended Requirements" icon="server">
    * 16+ CPU cores
    * 64GB+ RAM
    * 250GB+ storage
    * Suitable for production deployments
  </Card>
</CardGroup>

<Info>
  Hardware requirements may vary depending on your specific usage patterns, the number of concurrent users, and the amount of data processed.
</Info>

### Storage

<Accordion title="Database Storage">
  We recommend using:

  * **MongoDB**: For applications collections
  * **Vector Database**: one of Opensearch (recomended) or Redis Stack (with JSON and SEARCH modules)

  Ensure these databases are properly configured and accessible to the prismeai-functions microservice.
</Accordion>

<Accordion title="File Storage">
  `prismeai-functions` and `prismeai-llm` microservices require a RWX volume with at least 50GB and attached to a Kubernetes PVC.
</Accordion>

## Configuration Requirements

Several environment variables must be configured in the **prismeai-runtime** microservice to ensure proper functioning of installed Apps. If your deployment uses custom API ports modified by a container orchestrator or configuration, you'll need to adapt these values accordingly.

<success>
  All of these variables should already be initialized with our standard Helm charts deployment.
</success>

### Environment Variables

<Accordion title="Custom Code">
  Environment variables in prismeai-runtime :

  ```plaintext theme={null}
  APP_CONFIG_CustomCode_apiUrl='http://FUNCTIONS_HOST:80'
  ```

  Where `FUNCTIONS_HOST` refers to the domain from which the `prismeai-runtime` microservice can reach `prismeai-functions`.
</Accordion>

<Accordion title="Collections">
  Environment variables in prismeai-runtime :

  ```plaintext theme={null}
  COLLECTIONS_STORAGE_DRIVER=mongodb
  COLLECTIONS_STORAGE_HOST=mongodb://MONGO_HOST/collections
  ```

  Corresponding helm values in prismeai-runtime :

  ```yaml theme={null}
  prismeai-runtime:
    storage:
      collections:
        driver: 'postgresql' # Collections db driver REQUIRED: mongodb, postgresql
        url: '' # Collections db URI REQUIRED, example: mongodb+srv://prisme:password@mongodbcluster.example/collections?authSource=admin. Note the /collections path
        existingSecret: "core-prismeai-runtime-collections" # Auto generated secret : core-prismeai-runtime-collections
        secretKeys:
          url: ''  
  ```

  Where `MONGO_HOST` should be replaced with the host that allows the `prismeai-runtime` microservice to connect to MongoDB (e.g., `mongo` if `prismeai-runtime` and `mongo` are launched from the same docker-compose).
</Accordion>

<Accordion title="Crawler">
  Environment variables in prismeai-runtime :

  ```plaintext theme={null}
  APP_CONFIG_Crawler_apiUrl='http://SEARCHENGINE_HOST:80'
  ```

  Where `SEARCHENGINE_HOST` is the domain from which `prismeai-runtime` can reach `prismeai-searchengine`.
</Accordion>

<Accordion title="NLU">
  Environment variables in prismeai-runtime :

  ```plaintext theme={null}
  APP_CONFIG_NLU_apiUrl='http://NLU_HOST:80'
  ```

  Where `NLU_HOST` is the domain from which `prismeai-runtime` can reach `prismeai-nlu`.

  <Info>
    The NLU App is not required for the operation of AI Products, but provides advanced intent recognition capabilities if needed.
  </Info>
</Accordion>

<Accordion title="SendMail">
  Environment variables in prismeai-runtime :

  ```plaintext theme={null}
  APP_CONFIG_SendMail_apiKey='a mailgun API key'
  APP_CONFIG_SendMail_region='https://api.eu.mailgun.net/'
  APP_CONFIG_SendMail_domain='the mailgun domain'
  ```

  <Info>
    The SendMail App is currently compatible only with MailGun. It remains optional and is not required for the proper functioning of the AI products.
  </Info>
</Accordion>

# AI Products Initialization Process

Once you've confirmed that all prerequisites have been met, you can proceed with importing the Prisme.ai App Store and associated product workspaces. The initialization process uses the [Platform workspace bulk import](/products/ai-builder/versioning#bulk-import) to import workspace groups in the correct sequence, verifying functionality after each step.

<Info>
  The bulk import is performed from the **Platform** workspace, which is only accessible to super admins. Ensure you have super admin access before proceeding.
</Info>

## Importing Workspace Groups

Each group is imported using the Platform workspace's bulk import feature. For each group:

1. Open the **Platform** workspace
2. Navigate to **Versioning** > **Revert to a previous version (pull)**
3. Select the "**Release vXXX**" platform repository
4. Select the group to import and start the import
5. Monitor the progress from the **Activity** feed of the Platform workspace
6. Wait for the **`workspaces.bulkImport.completed`** event to appear
7. Verify the event contains no errors before proceeding to the next group

You can also trigger the import via the API:

```bash theme={null}
curl -X POST "${API_URL}/v2/workspaces/platform/versions/latest/pull" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"repository": {"id": "release"}, "groups": ["base1"]}'
```

<Warning>
  Always wait for the `workspaces.bulkImport.completed` event (with no errors) before importing the next group. Each group depends on the previous one being fully imported.
</Warning>

<Warning>
  Each group can be re-imported to reset all Apps/workspaces it contains, overwriting any modifications made in the studio since the first import.
</Warning>

## Group base1: Base Apps

This group contains foundational apps required by many other components.

### Key Components

<CardGroup cols="2">
  <Card title="Custom Code" icon="code">
    Enables execution of custom JS/Python code

    Requires the **functions** microservice to be online and configured
  </Card>

  <Card title="Prisme.ai API" icon="plug">
    Enables API calls to Prisme.ai from Automations (YAML files)
  </Card>
</CardGroup>

### Verification Tests

After importing the first group, run these tests to verify functionality :

<Accordion title="Testing Custom Code">
  1. Create a test workspace
  2. Install the `Custom Code` App in your test workspace
  3. Create a new function named `hello` with the following code:

  ```js theme={null}
  import fetch from 'node-fetch';
  const res = await fetch('https://httpbin.org/headers')
  return await res.json();
  ```

  1. Test the function using the green play button
  2. Verify that the `node-fetch` package has been properly installed and that you receive the expected website response without any import or internal errors
</Accordion>

## Group base2: Extended Base

This group contains extended base applications that build upon the first group.

### Key Components

<CardGroup cols="2">
  <Card title="Crawler" icon="spider-web">
    Web page indexing & search engine

    Requires the **crawler** and **searchengine** microservices
  </Card>

  <Card title="NLU" icon="comments">
    NLU engine

    Requires the **nlu** microservice
  </Card>

  <Card title="RedisSearch" icon="magnifying-glass">
    Interface with the redis-stack-server database, only used by Redis RAG database
  </Card>
</CardGroup>

### Verification Tests

After importing the second group, run this test to verify crawler functionality :

<Accordion title="Testing Crawler">
  1. Open the **Crawler/Crawl page** automation and run it with the top-right corner play button
  2. Open the **Activity** tab and regularly reload it until you see **Crawler.notifications event has been fired**
     * If this never occurs, check **prismeai-crawler** container logs (**apps namespace**) to resolve issues
  3. Open the **Crawler/Search page** automation and run it
  4. Verify that you receive the freshly indexed page result
</Accordion>

## Group extended: AI Products

This final group contains the main Prisme.ai AI products and is larger than the previous groups.

<Warning>
  Since this group is larger, the import may take several minutes. Monitor progress from the Platform workspace Activity feed and wait for the `workspaces.bulkImport.completed` event.
</Warning>

Several new workspaces should appear when you refresh the page after the import completes.

## Post-Import Configuration

After successfully importing all three groups, you need to proceed with the configuration of each AI Product to complete the setup process. It is advised to configure the products in the following minimum order :

* [Configure AI Governance](/self-hosting/configuration/ai-governance)
  * 1st, Generate a long-term token
  * Configure the `adminAccessToken`  setting
  * Configure the Ops Manager and upgrade the `core` helm deployment
* [Configure super admins](/self-hosting/configuration/ai-governance)
  * The AI Governance shortcut has appeared, elect a PlatformAdmin and PlatformManager
* [Configure LLM providers](/self-hosting/configuration/ai-knowledge)
  * In the AI Builder > AI Knowledge > Settings section
* [Create an AI SecureChat agent](/self-hosting/configuration/ai-securechat)
  * Finally, add this agent as a left-menu shortcut in the AI Governance > Products and Workspaces > Shortcuts section

## Troubleshooting

If you encounter issues during the initialization process, here are some common problems and their solutions:

<Accordion title="Custom Code Issues">
  Several critical AI products and Apps (including AI Knowledge) are built on Custom Code. If issues arise:

  1. Monitor the logs of the `prismeai-functions` service
  2. Look for these error messages:
     * `Failed npm install`
     * `Dependencies are still being installed from`
     * `Some dependencies are missing`
     * `TimeoutError`
     * `Failed running function`
  3. If a dependency is missing or still being installed after several minutes, re-save the **Custom Code** App for the affected workspace from the studio. This will prompt `prismeai-functions` to restart the installation (`Installing N modules...`).
  4. If the issue concerns functions of an App (indicated by the `app.` prefix in the logs), you'll need to re-publish the App.
</Accordion>

<Accordion title="Import Errors">
  If the bulk import reports errors in the `workspaces.bulkImport.completed` event:

  1. Check the `errors` field in the event payload for details on which workspaces failed
  2. Individual workspace import errors can also be checked in the `workspaces.imported` event emitted in each workspace's activity feed
  3. Common causes include slug conflicts (a workspace with the same slug already exists) or missing dependencies (a required group was not imported first)
  4. Resolve the errors and re-import the group — workspaces already up to date will be skipped automatically.

  If needed, you can force reimport all workspaces (including the ones theoritacally up to date) using the [bulk import API](/products/ai-builder/versioning#triggering-a-bulk-import).
</Accordion>

<Accordion title="Microservice Connectivity">
  If tests fail due to connectivity issues:

  1. Run the [Readiness API](/self-hosting/operations/testing#platform-readiness-api) to identify which services or dependencies are failing
  2. Ensure all required microservices are running
  3. Verify that the environment variables are correctly set
  4. Look at the logs of all services
</Accordion>

## Next Steps

<CardGroup cols="2">
  <Card title="Create your SecureChat" icon="wand-magic" href="/self-hosting/configuration/ai-securechat">
    Create your AI Secure Chat
  </Card>

  <Card title="AI Store" icon="shop" href="/self-hosting/configuration/ai-store">
    Learn how to manage and deploy agents in the Store
  </Card>

  <Card title="AI Knowledge" icon="book" href="/self-hosting/configuration/ai-knowledge">
    Organize collections and document-based agents
  </Card>

  <Card title="Create an agent" icon="wand-magic" href="/create-agents/overview">
    Learn more about agent creation
  </Card>
</CardGroup>