docker-compose-macos.yml

Overview

docker-compose-macos.yml is a Docker Compose configuration file tailored for macOS environments. Its primary purpose is to define and orchestrate multi-container Docker applications, specifically for running the Ragflow service along with its dependencies. This file extends a base configuration (docker-compose-base.yml) and customizes the service definitions to suit macOS-specific platform requirements and development workflows.

The configuration ensures proper service dependencies, platform compatibility (targeting linux/amd64), port mappings, environment variable management, volume mounts for persistent storage and configuration, and network setup. Additionally, it includes commented-out configuration snippets for an optional executor service, providing a template for future scalability or parallel task execution.

Detailed Explanation

Top-level keys

• include:
  Imports another Compose file (docker-compose-base.yml) to reuse common definitions and avoid duplication. This modular approach centralizes shared settings.

• services:
  Defines the containers to be run, their build context, runtime environment, volumes, ports, dependencies, and restart policies.

Services

ragflow

This is the main application service running the Ragflow server.

• ${SVR_HTTP_PORT} → 9380 (Ragflow app)

• 80 → 80 (HTTP)

• 443 → 443 (HTTPS) |
  | volumes | Mounts host directories and files into the container:

• ./ragflow-logs → /ragflow/logs (log storage)

• ./nginx/ragflow.conf → /etc/nginx/conf.d/ragflow.conf (Nginx site config)

• ./nginx/proxy.conf → /etc/nginx/proxy.conf (Nginx proxy config)

• ./nginx/nginx.conf → /etc/nginx/nginx.conf (Nginx main config) |

  env_file	Loads environment variables from a .env file.

• TZ=${TIMEZONE}: Timezone

• HF_ENDPOINT=${HF_ENDPOINT}: HuggingFace API endpoint

• MACOS=${MACOS:-1}: Flag to indicate Mac environment (default 1)

• LIGHTEN=${LIGHTEN:-1}: Possibly a feature flag or resource control |

  networks	Connects the container to the ragflow user-defined network.
  extra_hosts	Adds host entries for containers, mapping host.docker.internal to the host gateway IP, essential for Docker Desktop networking on macOS.

Commented-out executor service

This service is currently disabled (commented out) but provides an example for an executor container that depends on MySQL and shares volumes and environment settings with ragflow. It uses a pre-built image defined by ${RAGFLOW_IMAGE} and runs an entrypoint script with parameters.

Important Implementation Details

• Platform Compatibility:
  Setting platform: linux/amd64 is crucial on macOS, especially Apple Silicon (ARM-based), to ensure the container runs an x86_64 image, which might be required for certain binaries or dependencies.

• Health Checks for Dependencies:
  Using depends_on with condition: service_healthy ensures that the ragflow service only starts after the mysql database is fully available and healthy, preventing race conditions.

• Volume Mounts for Configuration and Logs:
  By mounting configuration files and logs from the host, developers can easily modify Nginx settings or inspect logs without rebuilding containers.

• Environment Variables and .env File:
  This pattern centralizes configuration and secrets management, facilitating environment-specific configurations without code changes.

• Extra Hosts for Docker Desktop:
  The extra_hosts entry allows containers to access services running on the host machine using host.docker.internal, which is often necessary for metrics, monitoring (e.g., Prometheus), or other integrations.

Interaction with Other Parts of the System

• docker-compose-base.yml:
  This file extends or includes base configuration shared across multiple environments or platforms. It likely defines common services such as mysql, networks, volumes, or other base-level settings.

• MySQL Service:
  ragflow depends on a MySQL service (defined likely in the base Compose file) for data persistence.

• Nginx Configuration:
  The mounted Nginx configuration files imply that ragflow container runs Nginx as a reverse proxy or web server component, providing HTTP(S) access and proxying requests internally.

• .env File:
  External environment configuration is expected to provide values like SVR_HTTP_PORT, TIMEZONE, HF_ENDPOINT, and others, allowing flexible deployment setups.

Usage Example

To start the Ragflow service on macOS:

# Ensure your .env file is properly configured with required variables.
docker-compose -f docker-compose-macos.yml up --build

This command will build and start the ragflow container after ensuring MySQL is healthy. Logs and config files will be accessible on the host via mounted volumes.

Mermaid Diagram: Service Workflow

The following flowchart visualizes the service dependencies and key runtime relationships defined in this Compose file.

flowchart TD
    A[Start Ragflow Service] -->|depends_on healthy| B[MySQL Service]
    B --> C{MySQL Healthy?}
    C -- Yes --> A
    C -- No --> B

    A --> D[Build Ragflow Image]
    D --> E[Run Ragflow Container]
    E --> F[Expose Ports 9380, 80, 443]
    E --> G[Mount Volumes: Logs, Nginx Configs]
    E --> H[Set Environment Variables]
    E --> I[Connect to ragflow Network]
    E --> J[Restart on Failure]

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#bbf,stroke:#333,stroke-width:1.5px
    style C fill:#f96,stroke:#333,stroke-width:1.5px
    style E fill:#afa,stroke:#333,stroke-width:1.5px

Summary

• docker-compose-macos.yml configures the Ragflow server container specifically for macOS with platform compatibility and dependency management.

• It mounts configurations and logs to the host for easy development and debugging.

• The service waits for MySQL to be ready before starting.

• Supports environment-driven configuration via .env.

• Provides extensibility with a commented-out executor service.

• Integrates with Docker Desktop networking conventions.

This file plays a critical role in streamlining local development and deployment of the Ragflow application on macOS systems.