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.

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.

Setup & Launch Instructions

1

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

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

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

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. Login with your MariaDB ID.

  2. Click Get License under the RAG Trial card.

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

  4. 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

Configure Database and Security Keys

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

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
triangle-exclamation

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

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.

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

Update the DB_HOST variables based on your database location:

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

circle-exclamation

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

6

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

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

Last updated

Was this helpful?