# Ray Cluster

> Distributed computing framework for ML.

- Category: AI & Machine Learning
- Difficulty: advanced
- Components: ray
- Tags: ray, distributed, ml, computing
- Source: https://docker.recipes/ai-ml/ray

## Overview

Ray is an open-source distributed computing framework developed by UC Berkeley's RISELab, designed to scale Python applications from single machines to large clusters. Ray provides a unified API for distributed computing that handles parallel processing, distributed training, hyperparameter tuning, and reinforcement learning workloads. The framework abstracts away the complexity of distributed systems while maintaining high performance through its actor-based model and efficient shared memory architecture.

This Ray cluster configuration establishes a distributed computing environment with a head node managing cluster coordination and worker nodes executing distributed tasks. The head node runs Ray's Global Control Store (GCS) and dashboard, while worker nodes connect automatically to form a cohesive computing cluster. Ray's architecture enables efficient task scheduling, automatic fault tolerance, and dynamic resource allocation across all nodes in the cluster.

Data scientists, ML engineers, and researchers working with computationally intensive Python workloads benefit most from Ray clusters. Organizations processing large datasets, training complex machine learning models, or running hyperparameter optimization experiments will find Ray's distributed capabilities essential. The framework particularly excels in environments requiring both high-throughput batch processing and low-latency model serving, making it valuable for production ML pipelines and research workflows.

## Features

- Distributed actor-based computing model with automatic task scheduling across cluster nodes
- Ray Dashboard for real-time cluster monitoring, task visualization, and resource utilization tracking
- Auto-scaling worker nodes with dynamic resource allocation and fault tolerance
- Ray Serve integration for distributed model serving with automatic load balancing
- Ray Tune support for distributed hyperparameter optimization and neural architecture search
- Shared object store using Apache Arrow for zero-copy data sharing between processes
- Ray Data for distributed data processing with support for ML preprocessing pipelines
- Built-in support for reinforcement learning workloads through Ray RLlib integration

## Use cases

- Distributed machine learning model training across multiple GPUs and nodes
- Large-scale hyperparameter tuning for deep learning experiments with Ray Tune
- High-throughput batch inference for computer vision and NLP models
- Distributed data preprocessing and ETL pipelines for ML workflows
- Reinforcement learning training environments with parallel episode collection
- Real-time model serving with automatic scaling based on request volume
- Monte Carlo simulations and financial risk modeling across distributed compute resources

## Prerequisites

- Minimum 8GB RAM per node (16GB+ recommended for ML workloads)
- Docker Engine 20.10+ with Docker Compose v2 support
- Network connectivity between nodes for cluster communication on port 6379
- Python programming knowledge for Ray application development
- Understanding of distributed computing concepts and parallel processing
- For GPU workloads: NVIDIA Docker runtime and compatible GPU drivers

## docker-compose.yml

```yaml
services:
  ray-head:
    image: rayproject/ray:latest
    container_name: ray-head
    command: ray start --head --dashboard-host=0.0.0.0 --block
    ports:
      - "8265:8265"
      - "6379:6379"
    networks:
      - ray

  ray-worker:
    image: rayproject/ray:latest
    command: ray start --address=ray-head:6379 --block
    deploy:
      replicas: 2
    depends_on:
      - ray-head
    networks:
      - ray

networks:
  ray:
    driver: bridge
```

## .env

```bash
# No additional config needed
```

## Usage notes

- Docs: https://docs.ray.io/
- Dashboard at http://localhost:8265 - cluster status and logs
- Connect from Python: ray.init('ray://localhost:10001')
- Scale workers via deploy.replicas in compose file
- Ray Serve for model serving, Ray Tune for hyperparameter tuning
- GPU support: add device reservations to worker service

## Troubleshooting

- ray-worker containers failing to start: Ensure ray-head container is fully initialized before workers attempt connection
- Dashboard not accessible on port 8265: Check firewall settings and verify ray-head container has --dashboard-host=0.0.0.0 parameter
- Workers not appearing in cluster: Verify network connectivity between containers and correct Redis port 6379 accessibility
- Out of memory errors during large computations: Increase Docker container memory limits or reduce Ray worker memory allocation
- Task scheduling delays or failures: Monitor Ray Dashboard for resource bottlenecks and consider scaling worker replicas
- Connection refused errors from Python clients: Ensure Ray client connects to correct head node address and GCS port is available

