upgrade_ragflow.mdx Documentation

Overview

The upgrade_ragflow.mdx file is a comprehensive upgrade guide document designed for users of the RAGFlow application. It provides detailed, step-by-step instructions on how to upgrade the RAGFlow system, including both its codebase and Docker images. The document explains upgrading to either the most recent nightly builds (nightly-slim or nightly) or to officially published releases. It also addresses important notes related to data persistence and volume management in Docker, and covers upgrade procedures in offline environments.

This file is primarily a Markdown-based documentation file with embedded React components (Tabs and TabItem) for interactive tabbed content, enhancing user experience by allowing users to switch easily between different upgrade image options.

Detailed Explanation of Content and Structure

1. Upgrade Overview Section

• Purpose: Introduces the upgrade topic, emphasizing the necessity to upgrade both the RAGFlow code and its Docker image simultaneously.

• Important Note: Warns users that upgrading does not delete existing data, but Docker volume removal commands can cause data loss.

2. Upgrade to Nightly Builds

Functionality:

• Provides instructions to upgrade RAGFlow to the most recent nightly Docker images, which exist in two variants:

  • nightly-slim: Docker image without embedding models.

  • nightly: Docker image including embedding models.

Steps:

1. Clone the RAGFlow GitHub repo.

2. Modify the .env file under ragflow/docker/ to specify which nightly image to use.

3. Pull and restart the Docker image using docker compose.

Usage Example:

git clone https://github.com/infiniflow/ragflow.git
# Edit ragflow/docker/.env to set:
# RAGFLOW_IMAGE=infiniflow/ragflow:nightly-slim
docker compose -f docker/docker-compose.yml pull
docker compose -f docker/docker-compose.yml up -d

The document uses tabbed UI components to display the .env variable for each image variant, improving clarity and usability.

3. Upgrade to Official Releases

Functionality:

• Guides users on upgrading to stable, officially published releases identified by version tags (e.g., v0.20.5).

• Provides options for "slim" or "full" Docker images, similar in concept to the nightly variants.

Steps:

1. Clone the repo.

2. Checkout the desired release tag.

3. Update the .env file to specify the release image.

4. Pull and restart the Docker container.

Usage Example:

git clone https://github.com/infiniflow/ragflow.git
git checkout -f v0.20.5
# Edit ragflow/docker/.env to set:
# RAGFLOW_IMAGE=infiniflow/ragflow:v0.20.5-slim
docker compose -f docker/docker-compose.yml pull
docker compose -f docker/docker-compose.yml up -d

Tabbed UI again facilitates switching between "slim" and "full" options.

4. Frequently Asked Questions (FAQs)

• Backing up knowledge bases: Clarifies that upgrading alone does not delete data, but volume removal commands do.

• Upgrading offline: Offers a procedure for upgrading in environments without Internet access by manually saving and loading Docker images.

Important Implementation Details

• The document leverages React components (Tabs and TabItem) to present alternative upgrade commands and configurations side-by-side.

• It references the .env file in the Docker directory to set environment variables controlling which Docker image version is deployed.

• The upgrade process always involves:

  • Synchronizing the local codebase with the desired version (using git clone and optionally git checkout).

  • Updating the Docker image environment variable.

  • Pulling and restarting Docker containers with docker compose.

• Explicit warnings about Docker volumes highlight the risk of data loss if volumes are removed, which is a critical consideration during upgrades.

Interaction with Other System Components

• GitHub Repository: The upgrade process requires cloning or checking out versions of the RAGFlow repository.

• Docker Environment: The file’s instructions interact heavily with Docker, specifically:

  • Docker Compose files located at docker/docker-compose.yml.

  • Docker images hosted on Docker Hub under the infiniflow/ragflow namespace.

  • Docker volumes storing persistent user data and knowledge bases.

• Configuration Files: The .env file under ragflow/docker/ is a key configuration file modified during upgrade to specify Docker image tags.

• RAGFlow Application Runtime: Upgrading code and Docker images ensures that the RAGFlow service runs the intended version with the appropriate embedded models.

Visual Diagram: Flowchart of Upgrade Process

flowchart TD
    A[Start Upgrade Process]
    A --> B{Choose Upgrade Type}
    B --> C[Nightly Builds]
    B --> D[Official Releases]

    C --> E[Clone RAGFlow Repo]
    E --> F[Update ragflow/docker/.env for nightly image]
    F --> G[Pull latest Docker image]
    G --> H[Restart Docker containers]
    H --> I[Upgrade Complete]

    D --> J[Clone RAGFlow Repo]
    J --> K[Checkout release tag]
    K --> L[Update ragflow/docker/.env for release image]
    L --> M[Pull release Docker image]
    M --> N[Restart Docker containers]
    N --> I

    I --> O[Verify Upgrade Success]

Diagram Explanation:

• The flowchart visualizes the two main upgrade paths: nightly builds and official releases.

• Both paths start with cloning the repository, followed by environment configuration and Docker image management.

• The process culminates in restarting Docker containers and verifying upgrade success.

• This diagram captures the linear, stepwise nature of the upgrade procedure, emphasizing the parallel structure between nightly and official release upgrades.

Summary

The upgrade_ragflow.mdx is a user-facing documentation file providing precise instructions to safely upgrade the RAGFlow system. It ensures users understand the need to synchronize code and Docker images, the implications for data persistence, and how to handle upgrades in both connected and offline environments. The use of interactive tabs enhances clarity for different upgrade options, and the inclusion of FAQs addresses common concerns.

This file is essential for maintaining the RAGFlow application lifecycle and ensuring users can smoothly transition between versions without data loss.

End of Documentation for upgrade_ragflow.mdx