docker-compose.yml

Overview

The docker-compose.yml file is a Docker Compose configuration that orchestrates multi-container Docker applications, specifically tailored for the Ragflow system. This file primarily defines how the Ragflow server container (ragflow) is set up, including its dependencies, networking, volume mounts, environment variables, ports, and restart policies.

Key functionalities include:

• Service orchestration: Defines the ragflow service that depends on a healthy mysql service.

• Container configuration: Specifies image, commands (commented out examples), container name, ports, volumes, environment variables, and network settings.

• Mounting configuration and logs: Ensures local configuration templates and log directories are mounted into the container.

• Optional executor service: Provides a commented-out example for an executor service with its own configurations.

• Prometheus monitoring readiness: Includes comments and settings to facilitate Prometheus monitoring integration.

This file acts as a central point for launching and configuring Ragflow-related containers in a consistent and reproducible manner.

Detailed Breakdown

Top-level Keys

• include
  Includes another docker-compose file: docker-compose-base.yml. This allows base configurations to be separated and reused.

• services
  Defines the individual containers (services) to be run.

Service: ragflow

This is the main application service for Ragflow.

Configuration

• depends_on
  Specifies that ragflow depends on the mysql service and will only start when mysql is healthy.

• image
  Uses the Docker image specified by the environment variable ${RAGFLOW_IMAGE}.

• container_name
  Sets the container name to ragflow-server for easier identification.

• ports
  Maps host ports to container ports:

  • ${SVR_HTTP_PORT}:9380 – Main Ragflow HTTP interface.

  • 80:80, 443:443 – Standard HTTP and HTTPS ports.

  • 5678:5678, 5679:5679 – Additional ports likely for service-specific communication.

  • 9382:9382 – MCP server port, must match --mcp-port if enabled.

• volumes
  Mounts local directories and files into the container:

  • Log directory (./ragflow-logs → /ragflow/logs)

  • Nginx configurations (./nginx/*.conf → /etc/nginx/)

  • History data agent source (../history_data_agent → /ragflow/history_data_agent)

  • Service configuration template (./service_conf.yaml.template → /ragflow/conf/service_conf.yaml.template)

  • Entrypoint script (./entrypoint.sh → /ragflow/entrypoint.sh)

• env_file
  Loads environment variables from .env.

• environment
  Defines environment variables inside the container:

  • TZ - Timezone, from ${TIMEZONE}

  • HF_ENDPOINT - HuggingFace endpoint (optional)

  • MACOS - Flag potentially indicating macOS host (optional)

• networks
  Connects the container to the ragflow Docker network.

• restart
  Policy is on-failure to restart the container automatically on failure.

• extra_hosts
  Adds a host entry mapping host.docker.internal to host-gateway allowing containers to access the host machine, useful for monitoring or debugging.

Comments & Examples

• There is an example command block (commented out) showcasing how to enable and configure the MCP (Modular Control Protocol) server inside the container.

• The file includes flags to enable or disable transports such as SSE or Streamable HTTP, indicating fine-grained control over communication protocols.

• Notes on host mode compatibility with transport flags.

• Prometheus configuration comments highlight how monitoring can be integrated.

Service: executor (Commented Out)

• Defines a secondary service executor based on the same image.

• Dependencies, volumes, environment variables, and networking are similar to ragflow.

• Uses a different entrypoint to run specific executor tasks.

• Also includes Prometheus-related extra_hosts configuration.

• Currently commented out, indicating optional or future use.

Important Implementation Details

• Volume mounts are critical for hot-reloading configuration (service_conf.yaml.template) and persisting logs.

• The use of .env file and environment variables provides flexibility for deployment on different environments without changing the compose file.

• Relying on depends_on with health checks for mysql ensures service startup ordering and stability.

• Extensive comments provide guidance for enabling advanced features like MCP server and transport options.

• The extra_hosts setting facilitates communication with the host, which is necessary for monitoring setups like Prometheus, especially on Docker Desktop environments.

Interactions with Other System Components

• MySQL service: Although not defined here, ragflow depends on a healthy MySQL container, indicating that this compose file likely works alongside another compose file or service managing the database.

• Nginx: The mounting of Nginx configuration files to /etc/nginx/ suggests that Nginx runs inside the container, reverse-proxying or handling HTTP/HTTPS traffic.

• Prometheus: Comments indicate integration points for Prometheus monitoring, requiring specific host network settings.

• History Data Agent: Mounting ../history_data_agent implies interaction with another component or service responsible for historical data processing.

• Entrypoint scripts: Custom scripts control container startup behavior, allowing flexible initialization.

Usage Example

To start the Ragflow server service with this compose file:

docker-compose -f docker-compose.yml up -d ragflow

This will:

• Wait for MySQL to be healthy.

• Launch the ragflow-server container with proper configuration, mounts, and environment.

• Expose the configured ports on the host machine.

• Handle restart on failure automatically.

Mermaid Flowchart Diagram

The following flowchart shows the main relationships and workflow in this compose file, focusing on the ragflow service setup and interactions.

flowchart TD
    A[Start docker-compose] --> B[Check mysql service health]
    B -->|Healthy| C[Launch ragflow container]
    C --> D[Mount volumes]
    C --> E[Set environment variables]
    C --> F[Expose ports]
    C --> G[Connect to ragflow network]
    C --> H[Set restart policy]
    C --> I[Add extra_hosts entry]
    D --> J[Mount logs, configs, nginx, history agent, entrypoint]
    J --> K[Container ready]
    E --> K
    F --> K
    G --> K
    H --> K
    I --> K
    K --> L[ragflow service running]

Summary

This docker-compose.yml file is a robust and configurable setup for running the Ragflow server container. It ensures proper dependencies, environment configuration, volume mounts for logs and configs, and networking. Comments provide useful insights for enabling advanced features and monitoring. The optional executor service configuration indicates extensibility for task execution within the Ragflow ecosystem.

This file typically works alongside other Docker Compose files and services such as MySQL, Nginx, and monitoring tools, forming a key part of the Ragflow deployment infrastructure.