Skip to content

README.md

Latest commit

 

History

History
379 lines (272 loc) · 7.96 KB

README.md

File metadata and controls

379 lines (272 loc) · 7.96 KB
Raw

RAGFlow Manager - Docker Deployment Guide

中文文档

This directory contains Docker deployment files for RAGFlow Manager, supporting multi-architecture deployment.

📁 Directory Structure

docker/
├── Dockerfile              # Multi-architecture Dockerfile
├── docker-compose.yml      # Docker Compose configuration
├── .env.example            # Environment variable example
├── build.sh                # Linux/Mac build script
├── build.bat               # Windows build script
└── README.md               # This document

🏗️ Supported Architectures

  • linux/amd64 (x86_64)
  • linux/386 (x86)
  • linux/arm64 (armv8)
  • linux/arm/v7 (armv7)
  • linux/mips64le (mips64, little-endian) ⚠️

⚠️ Note: MIPS architecture support may require special base images, and actual availability depends on your hardware and Docker version.

🚀 Quick Start

Option 1: Use Pre-built Images (Recommended)

  1. Prepare configuration file:
cd docker
cp .env.example .env
# Edit .env file to set your configuration
nano .env
  1. Start the service:
docker-compose up -d
  1. View logs:
docker-compose logs -f
  1. Access the service: Open browser and visit http://localhost:8082

Default admin account:

  • Username: admin
  • Password: admin123

Option 2: Build Images Locally

Linux/Mac Systems

# Enter project root directory
cd /path/to/ragflow-manager

# Build all architectures
./docker/build.sh multiarch

# Or build specific architecture (for quick testing)
./docker/build.sh single linux/amd64

# Specify version number
VERSION=1.0.0 ./docker/build.sh multiarch

Windows Systems

REM Enter project root directory
cd C:\path\to\ragflow-manager

REM Build all architectures
docker\build.bat multiarch

REM Or build specific architecture (for quick testing)
docker\build.bat single linux/amd64

REM Specify version number
set VERSION=1.0.0
docker\build.bat multiarch

⚙️ Configuration Instructions

Environment Variables

Main environment variables (complete list in .env.example):

Variable Name Description Default Value
SERVER_PORT Service listening port :8082
SERVER_MODE Running mode release
DATABASE_PATH Database file path /app/data/ragflow.db
JWT_SECRET JWT secret key (must be modified in production) -
JWT_EXPIRE JWT expiration time 24h
TZ Time zone Asia/Shanghai

Data Persistence

The default configuration persists the database file to the ./data directory:

volumes:
  - ./data:/app/data

Important Notes:

  • Ensure the ./data directory exists before first startup
  • Regularly back up the ./data/ragflow.db file

Custom Configuration File

If you need to use a custom configuration file:

# 1. Copy configuration file template
cp config.json.example docker/config.json

# 2. Edit configuration
nano docker/config.json

# 3. Uncomment the configuration file mount in docker-compose.yml
# volumes:
#   - ./config.json:/app/config.json:ro

🔧 Common Operations

Start Service

cd docker
docker-compose up -d

Stop Service

docker-compose down

Restart Service

docker-compose restart

View Logs

# View all logs
docker-compose logs

# Track logs in real-time
docker-compose logs -f

# View last 100 lines
docker-compose logs --tail=100

Update Images

# Pull latest images
docker-compose pull

# Recreate containers
docker-compose up -d

Enter Container

docker-compose exec ragflow-manager sh

Backup Data

# Backup database
cp ./data/ragflow.db ./data/ragflow.db.backup.$(date +%Y%m%d_%H%M%S)

# Or use Docker command
docker-compose exec ragflow-manager cp /app/data/ragflow.db /app/data/ragflow.db.backup

📊 Resource Limits

Default resource limits (can be adjusted in docker-compose.yml):

resources:
  limits:
    cpus: '2'
    memory: 512M
  reservations:
    cpus: '0.5'
    memory: 128M

Adjust these values based on actual load.

🔐 Security Recommendations

  1. Change default password: Change the admin password immediately after first login
  2. Change JWT secret: Set a random JWT_SECRET in .env 
    # Generate random secret
openssl rand -base64 32
  3. Use HTTPS: For production environments, it is recommended to add an Nginx reverse proxy with SSL configuration
  4. Limit port exposure: Only expose necessary ports
  5. Update regularly: Regularly pull the latest images

🌐 Reverse Proxy Examples

Nginx Configuration Example

server {
    listen 80;
    server_name ragflow.example.com;

    # Redirect to HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name ragflow.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8082;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket support (if needed)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Traefik Configuration Example

services:
  ragflow-manager:
    # ... other configurations ...
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.ragflow.rule=Host(`ragflow.example.com`)"
      - "traefik.http.routers.ragflow.entrypoints=websecure"
      - "traefik.http.routers.ragflow.tls.certresolver=myresolver"
      - "traefik.http.services.ragflow.loadbalancer.server.port=8082"

🐛 Troubleshooting

Container Fails to Start

# View detailed logs
docker-compose logs ragflow-manager

# Check container status
docker-compose ps

Database Permission Issues

# Ensure correct data directory permissions
sudo chown -R 1000:1000 ./data

Health Check Failure

# Check if port is correctly exposed
docker-compose port ragflow-manager 8082

# Test health check manually
docker-compose exec ragflow-manager wget -O- http://localhost:8082/

Insufficient Memory

Adjust memory limits in docker-compose.yml:

deploy:
  resources:
    limits:
      memory: 1G  # Increase to 1GB

📝 Multi-architecture Build Instructions

Prerequisites

  1. Docker version >= 19.03
  2. Enable Docker Buildx
  3. Configure QEMU (for cross-platform building)
# Install QEMU
docker run --privileged --rm tonistiigi/binfmt --install all

# Verify supported platforms
docker buildx ls

Build Process

# 1. Create builder
docker buildx create --name multiarch-builder --use

# 2. Start builder
docker buildx inspect --bootstrap

# 3. Build multi-architecture images
./docker/build.sh multiarch

# 4. Push to registry (optional)
REGISTRY=registry.example.com VERSION=1.0.0 ./docker/build.sh multiarch

Single Architecture Quick Build

For local testing, faster speed:

# Build current platform architecture
./docker/build.sh single linux/amd64

# ARM64
./docker/build.sh single linux/arm64

# ARMv7
./docker/build.sh single linux/arm/v7

📚 Reference Documentation

🆘 Get Help

If you encounter issues:

  1. Check the troubleshooting section of this document
  2. Check GitHub Issues
  3. View container logs: docker-compose logs -f
  4. Submit an Issue with detailed error information and environment configuration

📄 License

This project follows the main project license.