SAMO Chatbot - Deployment Guide

This document provides comprehensive examples for deploying the SAMO Chatbot using Docker Compose configurations.

---

Minimal Deployment

The minimal deployment is suitable for development, testing, or small-scale deployments where you want to use local file storage.

docker-compose-mini.yml

services:
  samo-ai-app:
    image: docker.asseco-ce.com/samo/tools/samo-ai-app:latest
    container_name: samo-ai-app
    ports:
      - "8080:8080"    
    volumes:
      - ./vector-store-dspy:/api/vector-store-dspy
      - ./requests.db:/api/requests.db
      - ./.env:/api/.env

.env Configuration (Minimal)

# LLM Configuration
AI_LLM_API_KEY=sk-your-openai-api-key-here
AI_LLM_PROVIDER=openai
AI_LLM_EMBEDDER_API_KEY=sk-your-openai-api-key-here
AI_LLM_EMBEDDER_PROVIDER=openai

# Local Vector Store (ChromaDB alternative)
AI_VECTOR_STORE=./vector-store-dspy

# Database Configuration (SQLite)
AI_DB_CONNECT_STRING=sqlite:///requests.db

# Security Configuration
AI_JWT_SECRET_KEY=your-strong-jwt-secret-key-here
AI_BASICKEY="base64-encoded-username:password"
AI_SECRET_KEY=your-strong-secret-key-here
AI_USER_SERVICE_URL=http://your-user-service-url.com
AI_AUTHORIZATION_METHOD=APPLICATION:DEMO.SAMO-ADMIN

# Azure Configuration
AI_AZDI_ENDPOINT=https://your-azure-di-endpoint.cognitiveservices.azure.com/
AI_AZDI_KEY=your-azure-di-key-here

# Server Configuration
AI_SERVER_PORT=8080
AI_SERVER_DEBUG_MODE=False

# Agent Configuration
AI_AGENT_ENABLE_DATA_QUERIES=true
AI_AGENT_METADATA_CACHE_SIZE=16

# ReAct model (used for FT retrieval, SQL generation, documentation search)
AI_AGENT_REACT_MODEL=openai/gpt-4o-mini
AI_AGENT_REACT_MAX_TOKENS=16000
AI_AGENT_REACT_TEMPERATURE=1.0

# Intent model (used for analyzing user intent)
AI_AGENT_INTENT_MODEL=openai/gpt-4o-mini
AI_AGENT_INTENT_MAX_TOKENS=2000
AI_AGENT_INTENT_TEMPERATURE=1.0

# Synthesis model (used for generating final responses)
AI_AGENT_SYNTHESIS_MODEL=openai/gpt-4o-mini
AI_AGENT_SYNTHESIS_MAX_TOKENS=5000
AI_AGENT_SYNTHESIS_TEMPERATURE=0.7

Features

• ✅ Uses local SQLite database
• ✅ Local ChromaDB vector store
• ✅ Minimal external dependencies
• ✅ Quick setup for development
• ✅ Single container deployment

---

Full Production Deployment

The full deployment includes PostgreSQL database and ChromaDB service, suitable for production environments with high availability and scalability requirements.

docker-compose-full.yml

services:
  server:
    image: docker.asseco-ce.com/samo/tools/samo-ai-app:latest
    ports:
      - 8080:8080
    volumes:
      - ./.env:/api/.env
    depends_on:
      - postgres
      - chromadb
    networks:
      - samo-network
    restart: unless-stopped

  postgres:
    image: postgres:16
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_DB=samodb
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - samo-network
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  chromadb:
    image: chromadb/chroma:0.6.3
    volumes:
      - chroma-data:/chroma/chroma
    networks:
      - samo-network
    ports:
      - "8000:8000"
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/api/v1/heartbeat"]
      interval: 10s
      timeout: 5s
      retries: 5

networks:
  samo-network:
    driver: bridge

volumes:
  postgres-data:
  chroma-data:

.env Configuration (Full Production)

# LLM Configuration
AI_LLM_API_KEY=sk-your-openai-api-key-here
AI_LLM_PROVIDER=openai
AI_LLM_EMBEDDER_API_KEY=sk-your-openai-api-key-here
AI_LLM_EMBEDDER_PROVIDER=openai

# ChromaDB Configuration (Remote)
AI_CHROMADB_HOST=http://chromadb
AI_CHROMADB_PORT=8000

# Database Configuration (PostgreSQL)
AI_DB_CONNECT_STRING=postgresql://postgres:postgres@postgres:5432/samodb

# Security Configuration
AI_JWT_SECRET_KEY=your-strong-jwt-secret-key-here
AI_SECRET_KEY=your-strong-secret-key-here
AI_USER_SERVICE_URL=http://your-user-service-url.com
AI_AUTHORIZATION_METHOD=APPLICATION:DEMO.SAMO-ADMIN
# Remove BASICKEY in production for security
# AI_BASICKEY="base64-encoded-username:password"

# Azure Configuration
AI_AZDI_ENDPOINT=https://your-azure-di-endpoint.cognitiveservices.azure.com/
AI_AZDI_KEY=your-azure-di-key-here

# Server Configuration
AI_SERVER_PORT=8080
AI_SERVER_DEBUG_MODE=False

# Agent Configuration
AI_AGENT_ENABLE_DATA_QUERIES=true
AI_AGENT_METADATA_CACHE_SIZE=16

# ReAct model (used for FT retrieval, SQL generation, documentation search)
AI_AGENT_REACT_MODEL=openai/gpt-4o
AI_AGENT_REACT_MAX_TOKENS=16000
AI_AGENT_REACT_TEMPERATURE=1.0
AI_AGENT_REACT_API_KEY=

# Intent model (used for analyzing user intent)
AI_AGENT_INTENT_MODEL=openai/gpt-4o-mini
AI_AGENT_INTENT_MAX_TOKENS=2000
AI_AGENT_INTENT_TEMPERATURE=1.0
AI_AGENT_INTENT_API_KEY=

# Synthesis model (used for generating final responses)
AI_AGENT_SYNTHESIS_MODEL=openai/gpt-4o-mini
AI_AGENT_SYNTHESIS_MAX_TOKENS=5000
AI_AGENT_SYNTHESIS_TEMPERATURE=0.7
AI_AGENT_SYNTHESIS_API_KEY=

# LIDS Configuration (if applicable)
AI_LIDS_URL=http://localhost:9090/web

# JDBC Configuration (for external database queries)
AI_DB_VENDOR=oracle
AI_DB_URL=database-host.example.com:1521:orcl
AI_DB_USERNAME=dbuser
AI_DB_PASSWORD=dbpass

Features

• ✅ PostgreSQL database for production reliability
• ✅ Dedicated ChromaDB service for vector operations
• ✅ Health checks for service monitoring
• ✅ Docker networks for service isolation
• ✅ Persistent volumes for data storage
• ✅ Service dependencies management
• ✅ Automatic restart policies
• ✅ Scalable architecture

---

Configuration Reference

Minimal vs Full Deployment Comparison

Feature	Minimal	Full Production
Database	SQLite (file-based)	PostgreSQL (service)
Vector Store	Local ChromaDB	ChromaDB service
Data Persistence	File volumes	Named volumes
Health Checks	❌ None	✅ Comprehensive
Networks	Default bridge	Custom isolated network
Restart Policy	Manual	Automatic
Use Case	Development, testing	Production, high-availability

---

Security Considerations

Generating Secure Keys

# Generate AI_SECRET_KEY (64 bytes hex)
-join ((48..57) + (97..102) | Get-Random -Count 64 | ForEach-Object {[char]$_})

# Generate BASICKEY (base64 encoded username:password)
$credentials = "username:password"
$bytes = [System.Text.Encoding]::UTF8.GetBytes($credentials)
[System.Convert]::ToBase64String($bytes)

---

Last Updated: November 19, 2025
Version: 2.0