📚 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

uxopian-ai_docker_example_arender.zip

Once extracted, you should have the following directory structure:

.
├── arender/
│   └── configurations/
│       ├── arender-custom-client.properties  # ARender AI host & button config
│       ├── arender-plugins.xml               # Plugin loader
│       └── toppanel-arender-ai-configuration.xml  # AI button definitions
├── config/
│   ├── application.yml                 # Main Spring configuration
│   ├── goals.yml                       # AI Goals definition
│   ├── llm-clients-config.yml          # API Keys and Model selection (OpenAI, Mistral, etc.)
│   ├── llm-clients-config.yml.example  # Example with all providers
│   ├── mcp-server.yml                  # Model Context Protocol config
│   ├── metrics.yml                     # Micrometer & Actuator 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 from the registry configured in your uxopian-ai-stack.yml:

docker pull artifactory.arondor.cloud:5001/uxopian-ai:2026.0.0-ft1-rc3-full
# Note: The OpenSearch and ARender images will be pulled automatically by the compose file.

Registry

The compose file uses artifactory.arondor.cloud:5001/ by default. If your organization hosts images on a different registry (e.g., docker.uxopian.com/preview/), update the image: fields in uxopian-ai-stack.yml accordingly.

🔹 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

About the dev Profile and the BFF Gateway

This starter kit ships with SPRING_PROFILES_ACTIVE=dev and no Gateway service. This lets you call the AI service directly — missing X-User-* headers are filled in with defaults. In a production deployment, deploy the Uxopian Gateway (BFF) in front of the AI service to handle authentication, role enforcement, and token propagation. The Gateway service is included in the compose file (commented out) — see the gateway block in uxopian-ai-stack.yml.

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

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

Contact your Uxopian representative for access to this package.

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.

See the Managing Prompts and Goals guide for detailed instructions. For this ARender integration, create a prompt with ID summarizeDocMd that uses [[${documentService.extractTextualContent(documentId)}]] to extract document content.

---

🔹 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):

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