Skip to content

docker-compose-deployment.md

Latest commit

 

History

History
331 lines (239 loc) · 6.25 KB

docker-compose-deployment.md

File metadata and controls

331 lines (239 loc) · 6.25 KB

Docker Compose Deployment Guide

This guide covers deploying LinX (灵枢) using Docker Compose for development and staging environments.

Prerequisites

  • Docker 20.10 or later
  • Docker Compose 2.0 or later
  • At least 8GB RAM
  • At least 50GB disk space

Quick Start

  1. Clone the repository:

    git clone https://github.com/asmoyou/LinX.git
cd LinX

  2. Configure environment variables:

    cp .env.example .env
# Edit .env with your configuration

  3. Start the platform:

    chmod +x infrastructure/scripts/start.sh
./infrastructure/scripts/start.sh all

  4. Access the platform:

Architecture

The Docker Compose setup includes the following services:

Infrastructure Services

  • PostgreSQL: Primary database for operational data
  • Redis: Message bus and caching
  • Milvus: Vector database for embeddings
  • MinIO: Object storage for files
  • etcd: Milvus metadata storage

Application Services

  • API Gateway: FastAPI REST API and WebSocket server
  • Frontend: React web application
  • FunASR Service: Optional standalone ASR service (profile-gated)

Configuration

Environment Variables

Key environment variables in .env:

# Database
POSTGRES_PASSWORD=your_secure_password
REDIS_PASSWORD=your_secure_password
MINIO_ROOT_PASSWORD=your_secure_password

# Security
JWT_SECRET=your_long_random_string

# LLM Providers
OLLAMA_BASE_URL=http://localhost:11434
OPENAI_API_KEY=your_key_here  # Optional

Volume Management

Data is persisted under the repository data/ directory:

  • data/postgres: PostgreSQL database
  • data/redis: Redis persistence
  • data/minio: MinIO object storage
  • data/milvus: Milvus vector database
  • data/etcd: etcd metadata

Service Management

Start Services

# Start all services
./infrastructure/scripts/start.sh all

# Start infrastructure only
./infrastructure/scripts/start.sh infrastructure

# Start application services only
./infrastructure/scripts/start.sh services

# Build images
./infrastructure/scripts/start.sh build

Stop Services

# Stop all services
docker compose down

# Stop and remove volumes (WARNING: deletes all data)
docker compose down -v

View Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f api-gateway

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

Restart Service

docker compose restart api-gateway

Health Checks

All services include health checks. Check service health:

# Check all services
docker compose ps

# Check specific service
docker compose ps api-gateway

# View health check logs
docker inspect dwp-api-gateway | grep -A 10 Health

Backup and Restore

Create Backup

chmod +x infrastructure/scripts/backup.sh
./infrastructure/scripts/backup.sh

Backups are stored in ./backups/ directory.

Restore from Backup

# Stop services
docker compose down

# Extract backup
cd backups
tar -xzf dwp_backup_YYYYMMDD_HHMMSS.tar.gz

# Restore PostgreSQL
docker compose up -d postgres
cat dwp_backup_YYYYMMDD_HHMMSS/postgres.sql | docker compose exec -T postgres psql -U dwp_user

# Restore Redis
docker cp dwp_backup_YYYYMMDD_HHMMSS/redis.rdb dwp-redis:/data/dump.rdb
docker compose restart redis

# Restore MinIO
docker run --rm \
  --network dwp_dwp-data \
  -v $(pwd)/dwp_backup_YYYYMMDD_HHMMSS/minio:/backup \
  -e MC_HOST_minio=http://minioadmin:password@minio:9000 \
  minio/mc \
  mirror /backup minio

# Restore Milvus
docker cp dwp_backup_YYYYMMDD_HHMMSS/milvus dwp-milvus:/var/lib/

# Start all services
docker compose up -d

Troubleshooting

Service Won't Start

  1. Check logs:

    docker compose logs service-name

  2. Check health:

    docker compose ps

  3. Restart service:

    docker compose restart service-name

Database Connection Issues

  1. Verify PostgreSQL is running:

    docker compose exec postgres pg_isready -U dwp_user

  2. Check connection from API:

    docker compose exec api-gateway python -c "from database.connection import get_db_session; print('OK')"

Out of Memory

  1. Check resource usage:

    docker stats

  2. Increase Docker memory limit in Docker Desktop settings

  3. Reduce service resource limits in docker-compose.yml

Port Conflicts

If ports are already in use, update in .env:

API_PORT=8001
FRONTEND_PORT=3001
POSTGRES_PORT=5433

Performance Tuning

PostgreSQL

Edit docker-compose.yml to add:

postgres:
  command:
    - "postgres"
    - "-c"
    - "max_connections=200"
    - "-c"
    - "shared_buffers=256MB"

Redis

Adjust memory limit:

redis:
  command: >
    redis-server
    --maxmemory 1gb
    --maxmemory-policy allkeys-lru

Milvus

For better performance, use SSD for Milvus data volume.

Security Considerations

  1. Change default passwords in .env
  2. Use strong JWT secret (at least 32 characters)
  3. Enable TLS for production (see Kubernetes deployment guide)
  4. Restrict network access using Docker networks
  5. Regular backups using the backup script
  6. Update images regularly for security patches

Monitoring

View Metrics

Resource Usage

# Real-time stats
docker stats

# Disk usage
docker system df

Upgrading

  1. Backup data:

    ./infrastructure/scripts/backup.sh

  2. Pull latest images:

    docker compose pull

  3. Rebuild custom images:

    docker compose build

  4. Restart services:

    docker compose down
docker compose up -d

  5. Run migrations:

    docker compose exec api-gateway alembic upgrade head

Next Steps