Docker Setup Guide for Lumi Chatbot

This guide will help you containerize and deploy the Lumi Chatbot using Docker and Docker Compose.

Prerequisites

Docker (20.10+)
Docker Compose (1.29+)
Git

Quick Start

1. Prepare Environment Variables

Copy the example environment file:

cp .env.docker.example .env

Edit .env and add your API keys:

OPENAI_API_KEY=sk-your-actual-key
PINECONE_API_KEY=pc-your-actual-key
PINECONE_INDEX_NAME=your-index-name
PINECONE_ENVIRONMENT=us-east-1-aws

2. Prepare Laravel

Generate application key:

cd lumi-backend
cp .env.example .env  # if it doesn't exist
php artisan key:generate

Copy the generated APP_KEY value to your .env file in the root.

3. Build and Run

From the project root:

# Build images
docker-compose build

# Start services
docker-compose up -d

# Check logs
docker-compose logs -f

4. Initialize Database

Run migrations:

docker-compose exec laravel php artisan migrate --force

5. Access the Application

Chatbot UI: http://localhost/ or http://localhost:8501
Laravel API: http://localhost/api
Admin Panel: http://localhost/admin
Embed Script: http://localhost/embed/chatbot-embed.js

Architecture

┌──────────────┐
│   Nginx      │  Port 80/443 (Reverse Proxy)
│   (optional) │  
└──────┬───────┘
       │
       ├─────────────► Laravel (Port 8000)
       │               - API endpoints
       │               - Filament admin
       │
       └─────────────► Streamlit (Port 8501)
                       - Chatbot interface

Service Details

Laravel Service

Container: lumi-laravel
Internal Port: 8000
Image: Custom PHP 8.2
Dependencies: SQLite database

Chatbot Service

Container: lumi-chatbot
Internal Port: 8501
Image: Custom Python 3.11
Dependencies: OpenAI, Pinecone, LangChain

Nginx Service (Optional)

Container: lumi-nginx
Ports: 80 (HTTP), 443 (HTTPS)
Purpose: Reverse proxy, SSL termination, rate limiting

Common Commands

Start Services

docker-compose up -d

Stop Services

docker-compose down

View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f laravel
docker-compose logs -f chatbot

Rebuild After Code Changes

# Rebuild specific service
docker-compose build laravel
docker-compose up -d laravel

# Rebuild all
docker-compose build
docker-compose up -d

Execute Commands in Containers

# Laravel artisan
docker-compose exec laravel php artisan migrate

# Install new PHP dependency
docker-compose exec laravel composer require package/name

# Python shell
docker-compose exec chatbot python manage_documents.py --help

Access Container Shell

# Laravel container
docker-compose exec laravel bash

# Chatbot container
docker-compose exec chatbot bash

File Synchronization

The docker-compose.yml uses volumes for development:

./lumi-backend:/var/www/html - Laravel code sync
./lumi-backend/chatbot:/app - Chatbot code sync

Changes to your local files will immediately reflect in the containers.

Production Deployment

Without Nginx (Simple)

If you don't need Nginx, comment it out in docker-compose.yml:

# services:
#   nginx:
#     ...

Access services directly: - Laravel: http://your-domain:8000 - Chatbot: http://your-domain:8501

With Nginx (Recommended)

Update nginx.conf: nginx server_name your-actual-domain.com;
Add SSL Certificates: bash # Place your SSL cert and key: nginx/ssl/cert.pem nginx/ssl/key.pem
Uncomment HTTPS block in nginx.conf
Update embed script URL: Edit chatbot-embed.js to use your domain: javascript chatUrl: 'https://your-domain.com',

Environment Variables for Production

Update .env:

APP_ENV=production
APP_DEBUG=false

Persistent Data

Database and uploads are preserved in named volumes:

# Backup database
docker-compose exec laravel sqlite3 database/database.sqlite .dump > backup.sql

# Restore database
cat backup.sql | docker-compose exec -T laravel sqlite3 database/database.sqlite

Troubleshooting

Chatbot Can't Connect to Laravel

Check network connectivity:

docker-compose exec chatbot ping laravel
docker-compose exec chatbot curl http://laravel:8000/api/health

Verify LARAVEL_API_BASE_URL in chatbot environment:

docker-compose exec chatbot env | grep LARAVEL

Permission Errors in Laravel

Fix storage permissions:

docker-compose exec laravel chown -R www-data:www-data storage bootstrap/cache
docker-compose exec laravel chmod -R 775 storage bootstrap/cache

Database Locked Errors

SQLite can have issues with concurrent access. Options:

Use MySQL/PostgreSQL: Add MySQL service to docker-compose.yml
Enable WAL mode: ```bash docker-compose exec laravel php artisan tinker

DB::statement('PRAGMA journal_mode=WAL;'); ```

Port Already in Use

Change ports in docker-compose.yml:

ports:
  - "8080:8000"  # Instead of 8000:8000

View Container Resource Usage

docker stats

Scaling

To run multiple chatbot instances:

chatbot:
  # ... existing config ...
  deploy:
    replicas: 3

Then use Nginx for load balancing:

upstream streamlit_chatbot {
    server chatbot:8501;
    server chatbot:8502;
    server chatbot:8503;
}

Monitoring

Health Checks

Both services have health checks configured.

Check status:

docker-compose ps

Healthy services show (healthy) status.

Logs

View real-time logs:

# All services
docker-compose logs -f

# Last 100 lines
docker-compose logs --tail=100

# Specific service
docker-compose logs -f chatbot

Cleanup

Remove All Containers and Volumes

docker-compose down -v

Remove Images

docker-compose down --rmi all

Full Cleanup

docker-compose down -v --rmi all
docker system prune -a

Alternative: Manual Docker Commands

If you prefer not to use docker-compose:

Build Laravel

cd lumi-backend
docker build -t lumi-laravel .
docker run -d -p 8000:8000 --name laravel lumi-laravel

Build Chatbot

cd lumi-backend/chatbot
docker build -t lumi-chatbot .
docker run -d -p 8501:8501 \
  -e OPENAI_API_KEY=sk-... \
  -e PINECONE_API_KEY=pc-... \
  --name chatbot lumi-chatbot

Next Steps

Set up automated backups
Configure monitoring (Prometheus, Grafana)
Set up CI/CD pipeline
Implement blue-green deployment
Add rate limiting at Nginx level
Configure log aggregation (ELK stack)

Support

For issues: 1. Check logs: docker-compose logs 2. Verify environment variables 3. Check network connectivity between services 4. Review health check status

Note: This Docker setup is production-ready but should be tested in a staging environment first before deploying to production.