# LightRAG Docker Deployment

A lightweight Knowledge Graph Retrieval-Augmented Generation system with multiple LLM backend support.

## 🚀 Preparation

### Clone the repository:

```bash
# Linux/MacOS
git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG
```
```powershell
# Windows PowerShell
git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG
```

### Configure your environment:

```bash
# Linux/MacOS
cp .env.example .env
# Edit .env with your preferred configuration
```
```powershell
# Windows PowerShell
Copy-Item .env.example .env
# Edit .env with your preferred configuration
```

LightRAG can be configured using environment variables in the `.env` file:

**Server Configuration**

- `HOST`: Server host (default: 0.0.0.0)
- `PORT`: Server port (default: 9621)

**LLM Configuration**

- `LLM_BINDING`: LLM backend to use (lollms/ollama/openai)
- `LLM_BINDING_HOST`: LLM server host URL
- `LLM_MODEL`: Model name to use

**Embedding Configuration**

- `EMBEDDING_BINDING`: Embedding backend (lollms/ollama/openai)
- `EMBEDDING_BINDING_HOST`: Embedding server host URL
- `EMBEDDING_MODEL`: Embedding model name

**RAG Configuration**

- `MAX_ASYNC`: Maximum async operations
- `MAX_TOKENS`: Maximum token size
- `EMBEDDING_DIM`: Embedding dimensions

## 🐳 Docker Deployment

Docker instructions work the same on all platforms with Docker Desktop installed.

### Start LightRAG  server:

```bash
docker-compose up -d
```

LightRAG Server uses the following paths for data storage:

```
data/
├── rag_storage/    # RAG data persistence
└── inputs/         # Input documents
```

### Updates

To update the Docker container:
```bash
docker-compose pull
docker-compose down
docker-compose up
```

### Offline docker deployment

LightRAG provide an docker image can be deployment in offline environments where internet access is limited or unavailable. All you need to do is modify `docker-compose.yml`: change image tag from `latest` to `offline`.

> Software packages requiring `transformers`, `torch`, or `cuda` will not be included in the offline dependency group. Consequently, document extraction tools such as Docling, as well as local LLM models like Hugging Face and LMDeploy, are outside the scope of offline installation support. These high-compute-resource-demanding services should not be integrated into LightRAG. Docling will be decoupled and deployed as a standalone service.

## 📦 Build Multi-Architecture Docker Images

### Prerequisites

Before building multi-architecture images, ensure you have:

- Docker 20.10+ with Buildx support
- Sufficient disk space (20GB+ recommended for offline image)
- Registry access credentials (if pushing images)

### 1. Setup Buildx Builder

Create and configure a multi-architecture builder:

```bash
# Create a new buildx builder instance
docker buildx create --name multiarch-builder --use

# Start and verify the builder
docker buildx inspect --bootstrap

# Verify supported platforms
docker buildx inspect multiarch-builder
```

You should see support for `linux/amd64` and `linux/arm64` in the output.

### 2. Registry Authentication

#### For GitHub Container Registry (ghcr.io)

**Option 1: Using Personal Access Token**

1. Create a GitHub Personal Access Token:
   - Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
   - Generate new token with `write:packages` and `read:packages` permissions
   - Copy the token

2. Login to registry:
   ```bash
   echo "YOUR_GITHUB_TOKEN" | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin
   ```

**Option 2: Using GitHub CLI**

```bash
gh auth token | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin
```

#### For Docker Hub

```bash
docker login
# Enter your Docker Hub username and password
```

#### For Other Registries

```bash
docker login your-registry.example.com
# Enter your credentials
```

### 3. Build Commands

#### A. Local Build (No Push)

Build multi-architecture images locally without pushing to registry:

**Normal image:**
```bash
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --file Dockerfile \
  --tag ghcr.io/hkuds/lightrag:latest \
  --load \
  .
```

**Offline image:**
```bash
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --file Dockerfile.offline \
  --tag ghcr.io/hkuds/lightrag:offline \
  --load \
  .
```

> **Note**: `--load` loads the image to local Docker, but only supports single platform. For multi-platform, use `--push` instead.

#### B. Build and Push to Registry

Build and directly push to container registry:

**Normal image:**
```bash
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --file Dockerfile \
  --tag ghcr.io/hkuds/lightrag:latest \
  --push \
  .
```

**Offline image:**
```bash
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --file Dockerfile.offline \
  --tag ghcr.io/hkuds/lightrag:offline \
  --push \
  .
```

#### C. Build with Multiple Tags

Add version tags alongside latest:

```bash
# Get version from git tag
VERSION=$(git describe --tags --abbrev=0 2>/dev/null || echo "v1.0.0")

# Build with multiple tags
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --file Dockerfile.offline \
  --tag ghcr.io/hkuds/lightrag:offline \
  --tag ghcr.io/hkuds/lightrag:${VERSION}-offline \
  --tag ghcr.io/hkuds/lightrag:offline-latest \
  --push \
  .
```

### 4. Verify Built Images

After building, verify the multi-architecture manifest:

```bash
# Inspect image manifest
docker buildx imagetools inspect ghcr.io/hkuds/lightrag:offline

# Expected output shows multiple platforms:
# Name:      ghcr.io/hkuds/lightrag:offline
# MediaType: application/vnd.docker.distribution.manifest.list.v2+json
# Platforms: linux/amd64, linux/arm64
```

Pull and test specific architectures:

```bash
# Pull AMD64 version
docker pull --platform linux/amd64 ghcr.io/hkuds/lightrag:offline

# Pull ARM64 version
docker pull --platform linux/arm64 ghcr.io/hkuds/lightrag:offline

# Test run
docker run --rm -p 9621:9621 ghcr.io/hkuds/lightrag:offline
```

### 5. Troubleshooting

#### Build Time is Very Slow

**Cause**: Building ARM64 on AMD64 (or vice versa) requires QEMU emulation, which is slower.

**Solutions**:
- Use remote cache (`--cache-from/--cache-to`) for faster subsequent builds
- Build on native architecture when possible
- Be patient - initial multi-arch builds take 30-60 minutes

#### "No space left on device" Error

**Cause**: Insufficient disk space for build layers and cache.

**Solutions**:
```bash
# Clean up Docker system
docker system prune -a

# Clean up buildx cache
docker buildx prune

# Check disk space
df -h
```

#### "failed to solve: failed to push" Error

**Cause**: Not logged into the registry or insufficient permissions.

**Solutions**:
1. Verify you're logged in: `docker login ghcr.io`
2. Check you have push permissions to the repository
3. Verify the image name matches your repository path

#### Builder Not Found

**Cause**: Buildx builder not created or not set as current.

**Solutions**:
```bash
# List builders
docker buildx ls

# Create and use new builder
docker buildx create --name multiarch-builder --use

# Or switch to existing builder
docker buildx use multiarch-builder
```

### 6. Cleanup

Remove builder when done:

```bash
# Switch back to default builder
docker buildx use default

# Remove multiarch builder
docker buildx rm multiarch-builder

# Prune build cache
docker buildx prune
```

### 7. Best Practices

1. **Use specific tags**: Avoid only using `latest`, include version tags
2. **Verify platforms**: Always check the manifest after pushing
4. **Monitor resources**: Ensure sufficient disk space before building
5. **Test both architectures**: Pull and test each platform variant
6. **Use .dockerignore**: Exclude unnecessary files to speed up build context transfer

### 9. Build Script Example

For convenience, create a build script `build-and-push.sh`:

```bash
#!/bin/bash
set -e

# Configuration
IMAGE_NAME="ghcr.io/hkuds/lightrag"
DOCKERFILE="Dockerfile.offline"
TAG="offline"

# Get version
VERSION=$(git describe --tags --abbrev=0 2>/dev/null || echo "dev")

echo "Building ${IMAGE_NAME}:${TAG} (version: ${VERSION})"

# Create builder if not exists
if ! docker buildx inspect multiarch-builder &>/dev/null; then
    echo "Creating buildx builder..."
    docker buildx create --name multiarch-builder --use
    docker buildx inspect --bootstrap
else
    docker buildx use multiarch-builder
fi

# Build and push
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --file ${DOCKERFILE} \
  --tag ${IMAGE_NAME}:${TAG} \
  --tag ${IMAGE_NAME}:${VERSION}-${TAG} \
  --push \
  .

echo "✓ Build complete!"
echo "Image pushed: ${IMAGE_NAME}:${TAG}"
echo "Version tag: ${IMAGE_NAME}:${VERSION}-${TAG}"

# Verify
docker buildx imagetools inspect ${IMAGE_NAME}:${TAG}
```

Make it executable and run:

```bash
chmod +x build-and-push.sh
./build-and-push.sh
```