Cerberus Aegis Docker Stack

A complete Docker stack for running the Cerberus Aegis LLM infrastructure, including Ollama for model serving, a FastAPI gateway for API access, and an optional OpenWebUI for user interaction.

🔧 Components

• Ollama: Serves LLM models locally with an API
• FastAPI Gateway: Routes requests to Ollama and provides additional API endpoints
• OpenWebUI (optional): Web interface for interacting with LLM models

🚀 Quick Setup

Prerequisites

• Docker and Docker Compose installed
• At least 8GB RAM recommended (16GB+ for larger models)
• 20GB+ free disk space

Installation

1. Clone or extract this directory

2. Create your environment file

   cp .env.example .env

   Edit the .env file to customize your setup if needed.

3. Build and start the stack

   docker compose build
   docker compose up -d

   To include OpenWebUI, use:

   docker compose --profile webui up -d

4. Check service health

   docker compose ps

   You can also check individual service logs:

   docker compose logs ollama
   docker compose logs fastapi-gateway
   docker compose logs openwebui

📡 API Endpoints

The FastAPI Gateway exposes the following endpoints:

• Health Check: GET http://localhost:8000/health
• List Models: GET http://localhost:8000/models
• Text Completion: POST http://localhost:8000/v1/completions
• Chat Completion: POST http://localhost:8000/v1/chat/completions
• Proxy to Ollama: POST http://localhost:8000/proxy/{path}

Example API Usage

Chat Completion Request:

curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is the capital of France?"}
    ],
    "model": "llama3"
  }'

🌐 Web Interface

If you enabled OpenWebUI, access it at: http://localhost:3000

Default credentials (if authentication is enabled):

• Create your account on first login

🔄 Managing the Stack

Stop all services:

docker compose down

Restart a specific service:

docker compose restart fastapi-gateway

View logs:

docker compose logs -f

Add new models:

docker exec -it cerberus_ollama ollama pull <model_name>

📁 Data Persistence

All data is stored in Docker volumes:

• cerberus_ollama_data: Stores downloaded models and Ollama configuration
• cerberus_webui_data: Stores OpenWebUI data and settings

🔒 Security Notes

• The default setup exposes API ports to the host machine
• For production use, consider adding authentication to the FastAPI gateway
• Review the .env file and adjust settings as needed

🛠️ Troubleshooting

Services not starting:

• Check logs with docker compose logs <service_name>
• Ensure you have enough disk space and memory
• Verify that required ports are not in use by other applications

Models not loading:

• Check Ollama logs: docker compose logs ollama
• Try manually pulling the model: docker exec -it cerberus_ollama ollama pull llama3

API connection issues:

• Verify the services are running: docker compose ps
• Check the FastAPI gateway logs: docker compose logs fastapi-gateway
• Ensure the OLLAMA_HOST environment variable is set correctly