Skip to content

README_DOCKER.md

Latest commit

 

History

History
297 lines (214 loc) · 6.2 KB

README_DOCKER.md

File metadata and controls

297 lines (214 loc) · 6.2 KB
Raw

Docker Deployment Guide

Language / 语言: English | 中文

Quick Start

1. Prepare Environment Variables

Create .env file:

OPENAI_API_KEY=your_api_key_here
API_PORT=8000

2. Build and Start

# Build image
docker-compose build

# Start service
docker-compose up -d

# View logs
docker-compose logs -f api

3. Access Service

What's Included in the Docker Image

The Docker image includes all dependencies needed for full functionality:

  • Python 3.11 with all pip dependencies
  • LaTeX (texlive) for PDF slide compilation
  • Node.js 20 with pptxgenjs for PPTX generation
  • react-icons + sharp for slide icons

No additional setup is required — PPTX generation works out of the box inside the container.

Directory Structure

.
├── Dockerfile              # Docker image definition
├── docker-compose.yml      # Docker Compose configuration
├── .dockerignore          # Docker ignore file
├── requirements.txt       # Python dependencies
├── src/build_pptx.js      # pptxgenjs PPTX builder (Node.js)
├── api_server.py         # FastAPI server
├── .env                  # Environment variables (not committed to Git)
├── exp/                  # Generated results (mounted as Volume)
├── catalog/              # Catalog files (mounted as Volume)
└── eval/                 # Evaluation results (mounted as Volume)

Data Persistence

The following directories are mounted as volumes, data will persist on the host:

  • ./exp → /app/exp: Generated course materials
  • ./catalog → /app/catalog: Catalog files
  • ./eval → /app/eval: Evaluation results

Common Commands

# Start service
docker-compose up -d

# Stop service
docker-compose down

# Restart service
docker-compose restart

# View logs
docker-compose logs -f

# Enter container
docker-compose exec api bash

# Rebuild image (after code updates)
docker-compose build --no-cache
docker-compose up -d

# Clean up (remove containers and images)
docker-compose down --rmi all

Configuration

docker-compose.yml

services:
  api:
    build: .                    # Use Dockerfile in current directory
    ports:
      - "${API_PORT:-8000}:8000"  # Port mapping
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}  # Read from .env
    volumes:
      - ./exp:/app/exp          # Data persistence
    restart: unless-stopped     # Auto restart

Environment Variables

Variable Description Default
OPENAI_API_KEY OpenAI API key Required
API_PORT API service port 8000

Production Deployment

1. Security Configuration

Modify docker-compose.yml:

services:
  api:
    # ... other configurations
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    # Resource limits
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G
        reservations:
          cpus: '1'
          memory: 2G

2. Use Reverse Proxy

Recommended to use Nginx as reverse proxy:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

3. Use HTTPS

Configure SSL certificate using Let's Encrypt or similar service.

Troubleshooting

Check Container Status

docker-compose ps

View Container Logs

docker-compose logs api
docker-compose logs -f api  # Real-time tracking

Check Container Resource Usage

docker stats instructional_agents_api

Enter Container for Debugging

docker-compose exec api bash
# Inside container
python -c "import os; print(os.environ.get('OPENAI_API_KEY'))"

Common Issues

  1. Port Already in Use

    # Modify API_PORT in .env
API_PORT=8001

  2. Permission Issues

    # Ensure directories have write permissions
chmod -R 755 exp catalog eval

  3. LaTeX Compilation Failed

    • Check if pdflatex exists in container: docker-compose exec api which pdflatex
    • View compilation logs: exp/{exp_name}/.cache/

  4. PPTX Generation Failed

    • Check if Node.js is available: docker-compose exec api node --version
    • Check if pptxgenjs is installed: docker-compose exec api node -e "require('pptxgenjs')"
    • Check NODE_PATH: docker-compose exec api npm root -g

  5. Insufficient Memory

    • LaTeX compilation and PPTX generation require more memory
    • Increase Docker memory limit or use larger instance

Updates and Maintenance

Update Code

# 1. Pull latest code
git pull

# 2. Rebuild image
docker-compose build

# 3. Restart service
docker-compose up -d

Backup Data

# Backup generated results
tar -czf exp_backup_$(date +%Y%m%d).tar.gz exp/

# Backup Catalog
tar -czf catalog_backup_$(date +%Y%m%d).tar.gz catalog/

Clean Old Data

# Clean old experiment results (use with caution)
find exp/ -type d -mtime +30 -exec rm -rf {} \;

Performance Optimization

  1. Use Multi-stage Build: Reduce image size
  2. Cache Dependencies: Optimize Dockerfile layer order
  3. Resource Limits: Prevent single task from consuming too many resources
  4. Concurrency Control: Limit number of concurrent tasks

Monitoring

Health Check

curl http://localhost:8000/health

Task Status

Query task status through API or view logs.

Migration to Another Server

  1. Export Data

    tar -czf data_backup.tar.gz exp/ catalog/ eval/

  2. On New Server

    # Copy files
scp data_backup.tar.gz user@new-server:/path/
scp docker-compose.yml .env user@new-server:/path/

# Extract data
tar -xzf data_backup.tar.gz

# Start service
docker-compose up -d

Support

For issues, please check: