circle-info
Webinar | Deploy MariaDB Cloud in Your Microsoft Azure Account. Retain Control.
Watch Nowarrow-up-right
search
Download MariaDBContact Us

Deployment

MariaDB AI RAG 1.1 (Beta) is a containerized Retrieval-Augmented Generation (RAG) solution designed for high-precision, citation-backed outputs. The system is deployed as a multi-container Docker stack, allowing components like the API brain, background workers, and document specialists to scale independently.

circle-info

As of AI RAG 1.1 release, native binary-based deployments (such as .deb or .rpm packages) are no longer available.

hashtag
Prerequisites

Ensure your environment meets the following requirements before starting the deployment:

  • Hardware: Minimum 4 CPU cores, 8 GB RAM, and 20 GB free disk space.

  • Operating System: 64-bit Linux

  • Software: Docker Engine and Docker Compose (v2.x+) must be installed.

  • Mandatory Credentials:

    • MariaDB License Key: A valid key is required for the application to pass the startup check.

    • AI Provider API Keys: Credentials for chosen AI providers (e.g., Google Gemini or OpenAI).

  • Database: A MariaDB 11.8+ instance is required for native vector search support.

hashtag
Setup & Launch Instructions

1

hashtag
Prepare Your Directory

Create a dedicated deployment folder on your host machine and navigate into it:

mkdir mariadb-rag-deployment
cd mariadb-rag-deployment
2

hashtag
Obtain Configuration Files

Download the following essential files from the public AI RAG GitHub repository and place them in your new folder:

  1. docker-compose.dockerhub-dev.ymlarrow-up-right: The blueprint defining all services in the stack.

  2. config.env.secure: The template containing all necessary environment variables.

3

hashtag
Create Local Storage Directory

Manually create these folders to prevent Docker from assigning 'root' permissions, which can cause access errors later:

mkdir uploaded_files
mkdir logs
4

hashtag
Obtain and Configure the MariaDB License Key

The application performs a mandatory validation check at startup and will fail to start if this key is missing, invalid, or expired. Each license is valid for 30 days from the day of generation, and you can generate a maximum of four at a time.

To grab your license step-by-step:

  1. Navigate to the MariaDB License Portalarrow-up-right.

  2. Login with your MariaDB ID.

  3. Click Get License under the RAG Trial card.

  4. Click Generate License. You may then View, Copy, or Download the license information.

  5. Paste this key into your config.env.secure file as MARIADB_LICENSE_KEY.

circle-info

MariaDB Trial License Keys are valid for 30 days from the date of generation. You may generate multiple licenses based on your subscription tier

5

hashtag
Configure Database and Security Keys

Open config.env.secure in a text editor to set your environment variables.

hashtag
Security & Unified Authentication

To enable unified authentication across the API and MCP server, set these three variables to the same secure string

  • SECRET_KEY

  • JWT_SECRET_KEY

  • MCP_AUTH_SECRET_KEY

circle-check

Secure String Generation

You may generate a secure 32-character string to assign to the three variables using openssl rand -hex 32

triangle-exclamation

Using a unique, randomly generated key prevents "replay attacks" and ensures that only your authorized MCP Gateway can trigger heavy-lifting tasks in the RAG API.

hashtag
AI Provider Setup Examples

Choose your preferred provider by configuring the following variables:

LLM_PROVIDER=gemini
LLM_MODEL=gemini-2.0-flash
GEMINI_API_KEY=your_gemini_key_here
EMBEDDING_PROVIDER=gemini
embedding_model=text-embedding-004

hashtag
Reranking & Search Accuracy

Reranking ensures that the most relevant document chunks are sent to the AI model, significantly reducing "hallucinations".

  • RERANKING_ENABLED: Set to true to activate the secondary search pass.

  • RERANKING_MODEL_TYPE: Defaults to flashrank (local/CPU efficient). Cloud options include cohere.

  • RERANKING_MODEL_NAME: The specific model used for scoring. Default: ms-marco-MiniLM-L-12-v2.

hashtag
Database Configuration

These variables define how the application connects to your MariaDB 11.8+ instance.Common Connection Variables:

  • DB_PORT: The port your database is listening on (Default: 3306).

  • DB_USER: The username for database access.

  • DB_PASSWORD: The password for the specified user.

  • DB_NAME: The name of the database schema.

circle-exclamation

SSL Mandatory for Cloud Databases

For cloud-hosted instances, you must set DB_SSL_ENABLED=true to ensure secure, encrypted communication over the public internet.

Update the DB_HOST variables based on your database location:

Set DB_HOST=mariadb. Hostnames must match internal container names.

circle-exclamation

hashtag
It is CRITICAL that these Server Ports must point to the internal Docker service names

APP_HOST=rag-api MCP_HOST=rag-api MCP_MARIADB_HOST=rag-api

6

hashtag
Launch the Application

Run the following command to start the service

docker compose -f docker-compose.dockerhub-dev.yml --env-file config.env.secure
7

hashtag
Verify and Access

Check the status of your services:

Check status
docker compose -f docker-compose.dockerhub-dev.yml ps

Once services are Up or Healthy, access the interactive Swagger UI to view all API documentation and test endpoints:

  • URL: http://localhost:8000/docs

PreviousManagementNextNetwork and Firewall Requirements

Last updated

Was this helpful?