Migration v27

Step-by-step guide for migrating an existing Prisme.ai installation from legacy products (Knowledges, AI Store) to the new v27 platform products (Agent Creator, LLM Gateway, Storage)

This guide walks you through migrating a self-hosted Prisme.ai installation from the legacy AI products (AI Store, Knowledges, …) to the new platform products (Agent Creator, LLM Gateway, Storage - vector store, …).

The migration is split into four phases:

1. Infrastructure update

   Update Helm values, image tags, and environment variables.

2. First connection

   Log in as super admin and create your organization.

3. Products initialization

   Import the new platform workspaces in the correct order.

4. Post-import configuration

   Migrate providers, models, vector store and organization settings.

1. Infrastructure update

1.1 Update the Console image

In your Helm core-values.yaml, update the prismeai-console block to use the unified platform image:

After

prismeai-console:
  enabled: true
  image:
    repository: registry.gitlab.com/prisme.ai/prisme.ai/prisme.ai-platform
    tag: ...

prismeai-console:
  enabled: true
  image:
    tag: ...

1.2 Bump all service & app tags

Update all core service and app image tags to the latest release. The available tags are listed on the Prisme.ai releases page.

1.3 Migrate LLM & vector store credentials

If your LLM and vector store credentials are currently injected through environment variables on prismeai-runtime, you need to duplicate the existing Knowledges variables under the new LLM Gateway and Storage prefixes.

The string after llm-gateway_ or storage_ is the secret name as it will be consumed by the LLM Gateway and Storage workspaces. You can rename either side as long as the prefix matches.

LLM providers

Duplicate every WORKSPACE_CONFIG_ai-knowledge_* variable related to LLM providers into a WORKSPACE_SECRET_llm-gateway_* equivalent.

Examples:

Legacy variable	New variable
WORKSPACE_CONFIG_ai-knowledge_awsBedrockAccessKey	WORKSPACE_SECRET_llm-gateway_awsBedrockAccessKey
WORKSPACE_CONFIG_ai-knowledge_openaiApiKey	WORKSPACE_SECRET_llm-gateway_openaiApiKey

Vector store

Duplicate every WORKSPACE_CONFIG_ai-knowledge_* variable related to the vector store into a WORKSPACE_SECRET_storage_* equivalent.

Examples:

Legacy variable	New variable
WORKSPACE_CONFIG_ai-knowledge_opensearch_host	WORKSPACE_SECRET_storage_opensearch_host
WORKSPACE_CONFIG_ai-knowledge_opensearch_username	WORKSPACE_SECRET_storage_opensearch_username

Alternatively, these secrets can be entered directly from the Secrets page of the LLM Gateway and Storage workspaces, without touching environment variables.

1.4 Deploy

Deploy the updated Helm chart and wait for all pods to roll out successfully.

helm -n prismeai-core upgrade prismeai-core -f core-values.yaml prismeai/prismeai-core
helm -n prismeai-apps upgrade prismeai-apps -f apps-values.yaml prismeai/prismeai-apps

---

2. First connection

1. Log in as super admin

   Once all services are deployed, sign in to the platform with a super admin account — the accounts listed under config.admins in your Helm values.

2. Create your organization

   From the onboarding screen, create your organization:

   • Name — the display name shown across the UI.
   • Technical name — the unique identifier used throughout the platform. It cannot be changed after creation.
3. Open Builder

   After creation, you should be redirected to a near-empty platform with two links in the left menu: Builder and Govern. Open Builder.

---

3. Products initialization

The new AI products are imported in four sequential groups via the Platform workspace bulk import:

base1

Foundation apps (Custom Code, Prisme.ai API, …).

base2

Extended base (Crawler, NLU, RedisSearch, …).

extended

Legacy AI products (Knowledges, AI Store, …), which will disappear in a future release.

one-product

Main AI products (LLM Gateway, Storage, Governe, …).

For each group:

1. Open the Platform workspace

   The Platform workspace is only visible to super admins.

2. Trigger the bulk import

   Navigate to Settings → Versions → Platform Pull, then select the Release vXXX platform repository.

3. Select the group and start the import

   Pick the group, start the import, and close the modal.

4. Monitor progress

   From the Activity feed of the Platform workspace, wait for the workspaces.bulkImport.completed event before moving on.

5. Repeat for the next group

   Import the groups in order: base1 → base2 → extended → one-product.

Always wait for workspaces.bulkImport.completed (with no errors) before importing the next group — each group depends on the previous one.

---

4. Post-import configuration

Once all groups are imported, configure each new workspace in the order below.

4.1 Governe — bridge the legacy admin token

The new Governe workspace needs the admin token from the legacy one to perform the migration.

1. Copy the legacy token

   In Builder, open the legacy Governe workspace → Settings → Secrets and copy the value of adminAccessToken.

2. Paste it into the new workspace

   Open the NEW Governe workspace → Settings → Secrets, paste the value into adminAccessToken, then Save.

4.2 LLM providers

1. Open the Govern app

   From the left menu, open Govern → Models → Providers tab.

2. Import from Knowledges

   Open the ⋮ (three-dot) menu in the top-right corner and click Import from Knowledges.

3. Adjust default models and secret names

   First check that default models are correctly set.

   Then, for each imported provider, make sure:

   • The secret names match the secrets you configured via WORKSPACE_SECRET_llm-gateway_* environment variables.

   Hover the (i) icon next to a secret input to see the matching environment variable name.

4. (Optional) Configure secrets from the UI

   If you’d rather store the secrets on the platform itself instead of through env vars:

   1. Open Builder in a new tab.
   2. Open the LLM Gateway workspace → Settings → Secrets.
   3. Add or update the secrets, using the same names as referenced by your providers.
5. Save

   Save the providers configuration.

All LLM providers can be exported and re-imported from the three-dot menu — useful for replicating configuration across environments.

4.3 LLM models

1. Open the Models tab

   Still in Govern → Models, switch to the Models tab.

2. Import from Knowledges

   Open the ⋮ menu and click Import from Knowledges.

3. Verify each model

   For every imported model:

   • Open it and click Test — the model response is shown below the button.
   • For embedding models, ensure the dimensions option is properly set. This was often left undefined in legacy Knowledges and must now be explicit.

Models can also be exported / imported in bulk from the three-dot menu.

4.4 Vector store

1. Open the Infrastructure page

   From the Govern menu, open Infrastructure.

2. Pick a driver

   Select your vector store driver: Elasticsearch or OpenSearch.

3. Adjust credential secret names

   Make sure the credential secret names match the values you exposed via WORKSPACE_SECRET_storage_* environment variables.

   Hover the (i) icon next to a secret input to see the matching environment variable name.

   To configure secrets directly from the UI instead:

   1. Open Builder in a new tab.
   2. Open the Storage workspace → Settings → Secrets.
   3. Add or update the secrets.
4. Set the index prefix

   Replace vector_store_index_prefix with the prefix to use for your RAG indexes (e.g. prod_rag).

5. Save and Test

   Save the configuration, then click Test. If the test fails, review your environment variables, secrets, or database connectivity and try again.

The raw vector store configuration lives in Storage workspace settings — accessible via the Edit button at the top right of the Storage workspace.

4.5 Infrastructure checkup

While on the Infrastructure page, use the Test button at the bottom of the Services block to verify connectivity to all platform databases.

---

5. Organization configuration

5.1 Allowed models

1. Open your organization

   Open Organizations and select the organization you just created.

2. Open Agent controls

   Navigate to Agent controls.

3. Pick allowed models

   Select all models you want to make available (you can use Select all). Models can be reordered by drag-and-drop.

4. Set defaults

   Choose the default Completions and Embeddings models for the organization.

5. Save

   Scroll to the bottom of the page and click Save.

5.2 Join rules

Join rules control which users automatically become members of your organization.

1. Open Join Rules

   Navigate to the Join Rules page.

2. Add a rule

   Add a rule with:

   • Field: Email
   • Operator: matches (wildcard)
   • Value: * to match all authenticated users

   Or configure a more specific filter if you only want a subset of users to join automatically. Other users can still join with an invite code or be invited manually by an org admin.

Default role mapping

When Assign role is left to Default, legacy users matched by your rule will be assigned an organization role based on their old platform role:

Legacy platform role	Assigned org role
User	org:member
KnowledgeAdmin, KnowledgeUser	agent-maker
Builder	builder
Admin	org:admin
PlatformAdmin	org:owner

Default group mapping

When Add to groups is left empty, any group a legacy user belonged to will be automatically recreated in your organization, and the user will be added to it.

For more advanced rules — assigning different roles or groups based on email or SSO metadata — see the Join Rules documentation.

5.3 Appearance

Configure your platform branding: name, favicon, colors, terms of use, …

All appearance settings can be exported / imported via the three-dot menu in the top-right corner.

5.4 Menu editor

A default menu template is available here.

1. Download the template

   Download the JSON file from the URL above.

2. Import it

   Open the Menu Editor, click the three-dot menu in the top-right corner, and import the JSON file.

3. Save and refresh

   Save your changes and refresh the page — the left menu should now be populated.

---

Next steps

Governe

Deep-dive into identity, access, and join rules.