Docker Integration¶

This document provides comprehensive information about the Docker integration for the AI Assistant project.

Overview¶

The AI Assistant project includes full Docker support with pre-configured services for: - Main AI Assistant application - Redis for caching - SearXNG for web search capabilities - Optional PostgreSQL database

Quick Start¶

Prerequisites¶

Docker and Docker Compose installed on your system
At least 4GB of RAM available
Sufficient disk space for Docker images and volumes

Basic Setup¶

Clone the repository:

git clone <repository-url>
cd ai-assistant

Copy the Docker environment template:
```
cp .env.docker .env
```
Edit the .env file to configure your API keys:
```
nano .env
```
Make sure to set at least:
OPENAI_COMPATIBLE_API_KEY (or your preferred LLM provider)
SECRET_KEY (generate a long random string)
Start all services:
```
docker-compose up -d
```
Check the status:
```
docker-compose ps
```
Access the application:
AI Assistant: http://localhost (through Traefik)
Gradio Interface: http://localhost/gradio
Traefik Dashboard: http://localhost:8080
SearXNG Search: http://localhost/search
Redis: localhost:6379 (internal only)

Stopping the Services¶

docker-compose down

Services¶

AI Assistant Application¶

The main application service that provides the AI assistant API.

Container Name: ai-assistant
Port: 8000
Health Check: HTTP GET to /
Environment Variables: See .env.docker for complete list

Redis¶

Redis is used for caching and session management.

Container Name: ai-assistant-redis
Image: redis:7-alpine
Port: 6379
Persistence: Data is stored in a Docker volume
Health Check: Redis PING command

SearXNG¶

SearXNG provides privacy-focused web search capabilities.

Container Name: ai-assistant-searxng
Image: searxng/searxng:latest
Port: 8080
Configuration: Custom settings in searxng/settings.yml
Health Check: HTTP GET to /

PostgreSQL (Optional)¶

PostgreSQL database for future use (disabled by default).

Container Name: ai-assistant-postgres
Image: postgres:15-alpine
Port: 5432
Profile: postgres (must be explicitly enabled)

Configuration¶

Environment Variables¶

Key environment variables for Docker deployment:

Variable	Description	Default
`HOST`	Host to bind to	`0.0.0.0`
`PORT`	Port to bind to	`8000`
`ENVIRONMENT`	Environment mode	`production`
`REDIS_URL`	Redis connection string	`redis://redis:6379/0`
`SEARXNG_URL`	SearXNG URL	`http://searxng:8080`
`SECRET_KEY`	Application secret key	Must be set
`BASE_URL`	Base URL for the application	`http://localhost`
`BEHIND_PROXY`	Whether running behind a proxy	`true`

Traefik Configuration¶

The project includes Traefik as a reverse proxy with configuration in docker-configs/traefik.yml. Key features: - Single entry point for all services - Automatic service discovery - Path-based routing - Development dashboard - Basic metrics and logging

Customizing SearXNG¶

To customize SearXNG settings:

Edit searxng/settings.yml
Restart the service:
```
docker-compose restart searxng
```

Adding PostgreSQL¶

To enable PostgreSQL:

Start with the postgres profile:

docker-compose --profile postgres up -d

Update your .env file to use PostgreSQL:

POSTGRES_URL=postgresql://postgres:password@postgres:5432/langchain_agent_hub

Development¶

Development Mode¶

For development with hot reload:

Use the development Docker Compose file:

docker-compose -f docker-compose.yml -f docker-compose.dev.yml up

Or run locally with Docker services:

# Start only Redis and SearXNG
docker-compose up -d redis searxng

# Run the application locally
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Viewing Logs¶

View logs for all services:

docker-compose logs -f

View logs for a specific service:

docker-compose logs -f ai-assistant
docker-compose logs -f redis
docker-compose logs -f searxng

Debugging¶

Accessing Container Shells¶

# AI Assistant container
docker-compose exec ai-assistant bash

# Redis container
docker-compose exec redis sh

# SearXNG container
docker-compose exec searxng sh

Checking Redis¶

docker-compose exec redis redis-cli
> INFO
> KEYS *

Rebuilding Images¶

After making changes to the application:

# Rebuild without cache
docker-compose build --no-cache

# Rebuild specific service
docker-compose build ai-assistant

Production Considerations¶

Security¶

Change Default Secrets: Always change the default SECRET_KEY and Redis password
Network Security: Consider using custom networks for production
Resource Limits: Set appropriate resource limits in production

Resource Limits¶

Example production resource limits:

services:
  ai-assistant:
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 1G
        reservations:
          cpus: '0.5'
          memory: 512M

Backup and Recovery¶

Redis Backup¶

# Create backup
docker-compose exec redis redis-cli BGSAVE
docker cp ai-assistant-redis:/data/dump.rdb ./redis-backup.rdb

# Restore backup
docker cp ./redis-backup.rdb ai-assistant-redis:/data/dump.rdb
docker-compose restart redis

PostgreSQL Backup (if enabled)¶

# Create backup
docker-compose exec postgres pg_dump -U postgres langchain_agent_hub > backup.sql

# Restore backup
docker-compose exec -T postgres psql -U postgres langchain_agent_hub < backup.sql

Troubleshooting¶

Common Issues¶

Port Conflicts¶

If ports are already in use, modify the docker-compose.yml:

services:
  ai-assistant:
    ports:
      - "8001:8000"  # Use different host port

Permission Issues¶

If you encounter permission issues with volumes:

# Fix volume permissions
sudo chown -R 1000:1000 ./logs

Memory Issues¶

If services are running out of memory:

Check resource usage:
```
docker stats
```
Add swap space or increase available RAM

Service Won't Start¶

Check logs:
```
docker-compose logs service-name
```
Verify configuration:
```
docker-compose config
```
Check if all required environment variables are set

Health Checks¶

All services include health checks. To check health status:

docker-compose ps

Performance Optimization¶

Redis Optimization: Configure Redis memory limits in production
Application Scaling: Consider using Docker Swarm or Kubernetes for scaling
Caching: Ensure Redis is properly configured for your workload

Advanced Usage¶

Custom Networks¶

For more complex setups, you can define custom networks:

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true

External Services¶

To connect to external services instead of Docker ones:

services:
  ai-assistant:
    environment:
      REDIS_URL: redis://external-redis-host:6379/0
      SEARXNG_URL: https://external-searxng-instance.com

Multi-Stage Builds¶

For production, consider using multi-stage builds to reduce image size:

# Build stage
FROM python:3.12-slim as builder
# ... build steps ...

# Runtime stage
FROM python:3.12-slim as runtime
# ... copy only what's needed ...

Migration from Local Development¶

To migrate from local development to Docker:

Export Data: Export any local data you need to keep
Update Configuration: Use .env.docker as a template
Test Migration: Test in a staging environment first
Backup: Create backups before migration
Gradual Migration: Consider migrating service by service

Contributing¶

When contributing to the Docker setup:

Test changes with both docker-compose up and docker-compose --profile postgres up
Update documentation for any new environment variables
Include health checks for new services
Follow Docker best practices for security and performance