Research Agent - Docker Deployment

Phase 8 implementation: Complete Docker containerization with multi-stage build, resource limits, health checks, and Haiven infrastructure integration.

Quick Start

# Configure secrets
cd /mnt/apps/docker/ai/research-agent
cp .env.template .env
vi .env  # Add your API keys

# Deploy
docker compose build
docker compose up -d

# Verify
docker exec research-agent curl -f http://localhost:8000/health

Directory Structure

/mnt/apps/docker/ai/research-agent/
├── docker-compose.yml      # Service configuration
├── .env                    # Environment variables (secrets)
├── scripts/
│   └── backup.sh          # Database backup script
├── DEPLOYMENT.md          # Complete deployment guide
├── PHASE8_CHECKLIST.md    # Implementation checklist
└── README.md              # This file

/mnt/apps/src/research-agent/
├── Dockerfile             # Multi-stage build
├── app/                   # Application code
├── requirements.txt       # Python dependencies
└── ...

/mnt/storage/research-agent/
├── data/                  # SQLite database
├── cache/                 # Search result cache
├── crawl-cache/           # Web content cache
├── exports/               # Session exports
├── archives/              # Expired sessions
├── backups/               # Database backups
└── logs/                  # Application logs

Files Overview

Dockerfile

Path: /mnt/apps/src/research-agent/Dockerfile

Multi-stage build for optimized production image:
- Builder stage: Compiles Python dependencies
- Runtime stage: Minimal python:3.12-slim
- Non-root user: research (UID 1000)
- Health check: curl-based health endpoint
- Size: ~931MB

Docker Compose

Path: /mnt/apps/docker/ai/research-agent/docker-compose.yml

Complete service configuration:
- Networks: web + backend (external)
- Port mapping: 8010:8000
- Volumes: 5 mounted paths
- Resource limits: 4 CPU, 4GB RAM
- Logging: json-file with rotation
- Health checks: built-in
- Traefik: internal & external routing

Environment Template

Path: /mnt/apps/docker/ai/research-agent/.env

Configuration variables:
- API keys for external services
- Model configuration
- Research settings
- Lifecycle configuration

Backup Script

Path: /mnt/apps/docker/ai/research-agent/scripts/backup.sh

Automated database backup:
- Online SQLite backup (safe during writes)
- Integrity verification
- Compression for old backups
- Retention policy (30 days)
- Ready for cron scheduling

Documentation

Document	Purpose
`DEPLOYMENT.md`	Complete deployment guide with troubleshooting
`PHASE8_CHECKLIST.md`	Implementation verification checklist
`README.md`	This file

Configuration

Required Environment Variables

# API Keys (from Haiven secret management)
CRAWL4AI_API_TOKEN=your-token
LITELLM_API_KEY=your-key
LANGFUSE_PUBLIC_KEY=your-key
LANGFUSE_SECRET_KEY=your-key

Network Requirements

Ensure these Docker networks exist (external):

docker network create web --subnet 10.10.0.0/24
docker network create backend --subnet 10.10.1.0/24

Deployment

Build

cd /mnt/apps/docker/ai/research-agent
docker compose build

Start

docker compose up -d

Monitor

# View logs
docker compose logs -f research-agent

# Health check
docker exec research-agent curl -f http://localhost:8000/health

Backup Setup

# Schedule daily backup at 2:00 AM
(crontab -l 2>/dev/null; echo "0 2 * * * /mnt/apps/docker/ai/research-agent/scripts/backup.sh") | crontab -

Access Points

Service	URL	Purpose
Internal	`https://research.haiven.local`	Internal network access
External	`https://research.haiven.site`	Public internet access
Local	`http://localhost:8010`	Direct container access

Storage

All data persists in /mnt/storage/research-agent/:

Directory	Purpose
`data/`	SQLite database
`cache/`	Search result caching
`crawl-cache/`	Web content caching
`exports/`	Session export files
`archives/`	Expired session archives
`backups/`	Database backup files
`logs/`	Application logs

Monitoring

Health Check

Endpoint: GET /health (internal port 8000)
Interval: 30 seconds
Timeout: 10 seconds
Failure threshold: 3 retries

Prometheus Metrics

Port: 8000
Path: /metrics
Format: Prometheus exposition format

Logging

Driver: json-file
Max size: 50MB per file
Max files: 3 (automatic rotation)
Location: /mnt/storage/research-agent/logs/

Resource Configuration

Resource	Limit	Reservation
CPU	4.0 cores	0.5 cores
Memory	4GB	512MB

Troubleshooting

See DEPLOYMENT.md for comprehensive troubleshooting guide covering:
- Container startup issues
- Health check failures
- Database problems
- Backup script issues
- Traefik integration

Security

Non-root user (UID 1000) prevents privilege escalation
Multi-stage build reduces attack surface
Secrets via environment variables (never hardcoded)
TLS enforced for external access
Rate limiting prevents abuse

Maintenance

Daily

Monitor logs for errors
Automated backup runs at 2:00 AM

Weekly

Review Prometheus metrics
Check backup directory size

Monthly

Review resource utilization
Test restore from backup

Support

For issues or questions:
1. Check DEPLOYMENT.md troubleshooting section
2. Review application logs: docker compose logs research-agent
3. Test health endpoint: docker exec research-agent curl http://localhost:8000/health

Next Steps

After successful deployment, proceed to Phase 9: Web UI Development
- Location: /mnt/apps/research-agent-plan/phases/phase-09-web-ui.md

Status: Production Ready (pending API key configuration)
Last Updated: 2025-12-30
Maintainer: Haiven Infrastructure Team