📚 Complete Guide: Uxopian AI Deployment & ARender Integration

This guide covers the entire process for deploying the Uxopian AI solution and integrating it into the ARender user interface.

📦 Part 1: Backend Deployment (AI Service)

This section covers the installation of the AI engine and its vector database. Two scenarios are possible: Docker (Recommended via Starter Kit) or Standalone (Native Java).

🚀 Scenario A: Docker Deployment (Starter Kit)

The Starter Kit provides a ready-to-use stack containing the AI service, an OpenSearch node, and a basic ARender stack for testing.

🔹 Step 1: Download and Structure

Download the Download the uxopian-ai_docker_example.zip archive. Once extracted, you should have the following directory structure:

.
├── config
│   ├── application.yml                 # Main Spring configuration
│   ├── goals.yml                       # AI Goals definition
│   ├── llm-clients-config.yml          # API Keys and Model selection (OpenAI, Mistral, etc.)
│   ├── mcp-server.yml                  # Model Context Protocol config
│   ├── opensearch.yml                  # Vector database connection
│   └── prompts.yml                     # Pre-defined prompts
├── gateway-application.yaml            # Gateway config (if used)
└── uxopian-ai-stack.yml                # The docker-compose file

🔹 Step 2: Pull Images

Pull the required images (example via Cloudsmith or Artifactory):

docker pull [docker.uxopian.com/preview/uxopian-ai:2026.0.0-ft1-rc3-full](https://docker.uxopian.com/preview/uxopian-ai:2026.0.0-ft1-rc3-full)
docker pull [docker.uxopian.com/preview/gateway:2026.0.0-ft1-rc3-full](https://docker.uxopian.com/preview/gateway:2026.0.0-ft1-rc3-full)
# Note: The OpenSearch image is public and will be pulled automatically by the compose file.

🔹 Step 3: Environment Variable Configuration

The uxopian-ai-stack.yml file orchestrates the containers. Do not modify the YAML structure, but you must adapt the environment variables of the uxopian-ai-standalone service to ensure network communication.

There are two distinct communication flows to configure:

1. Server-to-Server Communication (AI Backend to ARender)

The AI must contact the ARender Service Broker to read document text. This happens via the internal Docker network.

Variable	Description	Example (Internal Docker)
`RENDITION_BASE_URL`	Internal URL of the ARender Service Broker.	`http://dsb-service:8761`
`OPENSEARCH_HOST`	OpenSearch container hostname.	`uxopian-ai-opensearch-node1`
`OPENSEARCH_PORT`	OpenSearch port.	`9200`

2. Client-to-Server Communication (Browser to AI)

The ARender Interface (running in the user's browser) must contact the AI.

Variable	Description	Example (Public)
`UXOPIAN_AI_PORT`	Internal listening port of the service.	`8080`
`APP_BASE_URL`	Public URL of the AI application (for callbacks).	`http://localhost:8085`
`SPRING_PROFILES_ACTIVE`	Configuration profile (`dev` disables strict security).	`dev`

Note on ARender UI

In the ARender UI container configuration, do not forget to set UXOPIAN_AI_HOST to the public URL of the AI (e.g., http://localhost:8085 or https://ai.my-domain.com).

🔹 Step 4: Start

docker-compose -f uxopian-ai-stack.yml up -d

☕ Scenario B: Manual Installation (ZIP / Java)

Use this method for deployment on a standard server (VM Linux/Windows) without Docker.

Prerequisites:

Java 21 Runtime Environment (JRE).
OpenSearch 2.x installed and running on the network.

🔹 Step 1: Installation

Download the complete package: ai-standalone-2026.0.0-ft1-rc3-complete-package.zip.
Unzip the archive:

unzip ai-standalone-2026.0.0-ft1-rc3-complete-package.zip
cd ai-standalone

🔹 Step 2: Configuration

All files are located in the config/ folder. You must edit them:

opensearch.yml: Enter the IP and credentials of your external OpenSearch cluster.
llm-clients-config.yml: Configure your LLM providers (Azure OpenAI, Mistral, etc.) and API keys.
application.yml: General settings (ports, logs).

Documentation is available at: Configuration

🔹 Step 3: Execution

Run the Java service:

java -jar ai-standalone.jar

Production Recommendations

Use JAVA_OPTS to allocate enough memory (e.g., -Xmx4g).
Place the service behind a Reverse Proxy (NGINX/Apache) to handle SSL.

🖥️ Part 2: ARender Configuration (Frontend)

This section details how to modify the ARender configuration to display AI buttons and interact with the deployed backend.

📂 Configuration File Structure

Whether using Docker or manual installation, prepare the following files according to this structure:

.
├── configurations
│   ├── arender-custom-client.properties      # Activates scripts and configures AI host
│   ├── arender-plugins.xml                   # Imports Spring beans
│   └── toppanel-arender-ai-configuration.xml # Defines the button and JS action
└── public
    ├── web-components.css                    # Uxopian component styles
    └── web-components.js                     # Uxopian component JS logic

🔹 Step 1: Prompt Creation (Backend)

Before adding the button, the AI must know what to do. Create a prompt via the API.

URL: POST /api/v1/admin/prompts
Body:

{
  "id": "summarizeDocMd",
  "role": "user",
  "content": "Summarize the following document: \n [[${documentService.extractTextualContent(documentId)}]]",
  "defaultLlmProvider": "openai",
  "defaultLlmModel": "gpt-4o",
  "temperature": "0.7"
}

Note: [[...]] is a server-side instruction to inject the document text.

🔹 Step 2: Property Configuration (`arender-custom-client.properties`)

Edit configurations/arender-custom-client.properties. This file links the UI to the AI service.

# 1. Load CSS (ARender Style + AI Style)
style.sheet=css/arender-style.css,web-components.css

# 2. Load Web Component script at startup
arenderjs.startupScript=web-components.js

# 3. Add 'aiMenu' to the top toolbar (middle section)
topPanel.section.middle.buttons.beanNames=addStickyNoteAnnotationButton,annotationCreationOpenCreation,documentBuilderButton,aiMenu

# 4. Configure Public AI URL
# This is the address the user's browser will call
uxopian.ai.host=http://localhost:8085
# Production example: [https://ai.my-company.com](https://ai.my-company.com)

# 5. (Optional) Disable visual logs (toasters)
toaster.log.info.enabled=false

🔹 Step 3: Register Plugin (`arender-plugins.xml`)

Edit configurations/arender-plugins.xml to import your button configuration file.

<?xml version="1.0" encoding="UTF-8"?>
<beans default-lazy-init="true" default-autowire="no"
    xmlns="[http://www.springframework.org/schema/beans](http://www.springframework.org/schema/beans)"
    xmlns:xsi="[http://www.w3.org/2001/XMLSchema-instance](http://www.w3.org/2001/XMLSchema-instance)"
    xsi:schemaLocation="[http://www.springframework.org/schema/beans](http://www.springframework.org/schema/beans)
        [http://www.springframework.org/schema/beans/spring-beans.xsd](http://www.springframework.org/schema/beans/spring-beans.xsd)">

    <import resource="plume.xml"/>
    <import resource="html-plugin.xml"/>

    <import resource="toppanel-arender-ai-configuration.xml"/>

</beans>

🔹 Step 4: Button Definition (`toppanel-arender-ai-configuration.xml`)

This XML file defines the dropdown menu and the button triggering the AI call. It contains injected JavaScript code ($wnd.createChat).

<?xml version="1.0" encoding="UTF-8"?>
<beans default-lazy-init="true" default-autowire="no"
    xmlns="[http://www.springframework.org/schema/beans](http://www.springframework.org/schema/beans)"
    xmlns:xsi="[http://www.w3.org/2001/XMLSchema-instance](http://www.w3.org/2001/XMLSchema-instance)"
    xsi:schemaLocation="[http://www.springframework.org/schema/beans](http://www.springframework.org/schema/beans)
        [http://www.springframework.org/schema/beans/spring-beans.xsd](http://www.springframework.org/schema/beans/spring-beans.xsd)">

    <bean id="aiMenu"
       class="com.arondor.viewer.client.toppanel.presenter.SubMenuButtonPresenter">
       <constructor-arg value="aiMenu" />
       <constructor-arg value="AI" />
       <constructor-arg value="standardButton fas fa-robot toppanelButton"/>
       <property name="enabled" value="true" />
       <property name="visibilityForTopPanel">
          <ref bean="topPanelVisibilityMode" />
       </property>
       <property name="orderedNamedList" value="summarizeDocMdButton" />
    </bean>

    <bean id="summarizeDocMdButton"
       class="com.arondor.viewer.client.toppanel.presenter.DropdownMenuItemPresenter">
       <constructor-arg value="summarizeDocMdButton"/>
       <constructor-arg value="Summarize Document"/>
       <constructor-arg value="standardButton fas fa-list toppanelButton"/>
       <property name="enabled" value="true" />
       <property name="closingOnClick" value="true" />
       <property name="buttonHandler">
          <bean class="com.arondor.viewer.client.jsapi.toppanel.JSCallButtonHandler">
             <property name="jsCode">
                <value>
try {
    // Call the global function exposed by web-components.js
    $wnd.createChat({
        endpoint: "${uxopian.ai.host}",   // Variable injected from .properties
        wsEndpoint: "${uxopian.ai.host}", // Variable injected from .properties
        request: {
            inputs: [{
                role: 'user',
                content: [{
                    type: 'PROMPT',
                    value: 'summarizeDocMd', // Prompt ID defined in Step 1
                    payload: {
                        // Get current document ID via ARender JS API
                        documentId: $wnd.getARenderJS().getCurrentDocumentId()
                    }
                }]
            }]
        }
    });
} catch(e) {
  console.log('Error launching AI Chat: ' + e);
}
                </value>
             </property>
          </bean>
       </property>
    </bean>
</beans>

🛠️ Part 3: Applying Changes (ARender Deployment)

Once your configuration files are ready, apply them to your ARender instance.

🅰️ Option A: Docker Integration (Custom Image Build)

If using Docker for ARender, you must build a new image containing these configurations. Volume mounting alone can sometimes cause permission issues or file overwrites.

1. Create Dockerfile At the root of your folder containing configurations/ and public/:

# Stage 1: File Preparation
FROM alpine as builder
WORKDIR /app
COPY configurations/ configurations/
COPY public/ public/

# Stage 2: Final ARender Image
FROM artifactory.arondor.cloud:5001/arender-ui-springboot:2023.16.0

# Copy XML/Properties configurations
COPY --from=builder /app/configurations/* /home/arender/configurations/

# Copy Web resources (JS/CSS)
COPY --from=builder /app/public/* /home/arender/public/

2. Build Image

docker build -t my-company/arender-ui-ai:custom .

3. Update docker-compose In your docker-compose.yml, replace the ui service image with my-company/arender-ui-ai:custom.

🅱️ Option B: Manual Installation (Server)

For a standard installation (Tomcat or Executable Jar):

Configurations: Copy the contents of your configurations/ folder (the 3 files) to your ARender installation's config folder ($ARENDER_HOME/configurations/).
Web Resources: Copy web-components.js and web-components.css to your installation's public folder ($ARENDER_HOME/public/).
Restart: Restart the ARender service to load the new Spring Beans.

📚 Complete Guide: Uxopian AI Deployment & ARender Integration

📦 Part 1: Backend Deployment (AI Service)

🚀 Scenario A: Docker Deployment (Starter Kit)

🔹 Step 1: Download and Structure

🔹 Step 2: Pull Images

🔹 Step 3: Environment Variable Configuration

1. Server-to-Server Communication (AI Backend to ARender)

2. Client-to-Server Communication (Browser to AI)

🔹 Step 4: Start

☕ Scenario B: Manual Installation (ZIP / Java)

🔹 Step 1: Installation

🔹 Step 2: Configuration

🔹 Step 3: Execution

🖥️ Part 2: ARender Configuration (Frontend)

📂 Configuration File Structure

🔹 Step 1: Prompt Creation (Backend)

🔹 Step 2: Property Configuration (arender-custom-client.properties)

🔹 Step 3: Register Plugin (arender-plugins.xml)

🔹 Step 4: Button Definition (toppanel-arender-ai-configuration.xml)

🛠️ Part 3: Applying Changes (ARender Deployment)

🅰️ Option A: Docker Integration (Custom Image Build)

🅱️ Option B: Manual Installation (Server)

🔹 Step 2: Property Configuration (`arender-custom-client.properties`)

🔹 Step 3: Register Plugin (`arender-plugins.xml`)

🔹 Step 4: Button Definition (`toppanel-arender-ai-configuration.xml`)