django-ray Documentation¶

Welcome to the django-ray documentation. django-ray is a Ray-based backend for Django Tasks that enables distributed task execution with database-backed reliability.

What is django-ray?¶

django-ray is a library that provides:

• RayTaskBackend - A Django Tasks backend
• RayTaskExecution model - Task execution tracking in your database
• TaskWorkerLease model - Worker coordination for distributed deployments
• django_ray_worker command - Management command to process tasks
• Django Admin integration - Monitor and manage tasks

Note: This repository also contains a testproject/ directory with example code demonstrating django-ray features. The testproject (including its REST API) is not part of the django-ray library - it's provided for learning and testing purposes only.

The bundled testproject includes a landing page that links to the sample API, admin, Ray dashboard, project resources, task stats, and a smoke-task trigger:

User Guide¶

• Getting Started - Installation and basic setup
• Configuration - All configuration options
• Worker Modes - Understanding execution modes
• Performance - Choosing task boundaries, batching, and RuntimeEnv strategy
• Observability - Versioned services, metrics, and live admin updates
• Compatibility - Supported versions, CI policy, and platform limits
• Compiled Graph Compatibility - Candidate and verified native capability tuples, probes, and canaries
• Task Definition - Defining and enqueueing tasks
• Queues - Working with task queues
• Retry & Error Handling - Configuring retries and handling failures

Deployment¶

• Kubernetes Deployment - Deploy to Kubernetes
• Docker - Running with Docker
• TLS Configuration - Securing Ray cluster communication
• Operator Runbook - Incident diagnosis and manual recovery

Reference¶

• CLI Reference - Command-line interface
• Settings Reference - All settings
• Durable Input Storage - Oversized JSON input storage and cleanup
• Result Storage - Oversized result backends and retrieval
• Handle Compatibility - Ray Core handle formats and migration policy
• API Reference - How to build your own API (with testproject examples)

Development¶

• Contributing - How to contribute
• Architecture - System design overview
• Workflow Plan Contract - Versioned plan vocabulary, classification, identity, and strategy eligibility
• ADR-0001: Workflow Plans - Why execution plans and strategies remain separate from Django task identity
• ADR-0002: Compiled Sessions - Initial local/direct CPU-pilot owner, deferred production topology, within-run reuse, admission, invalidation, and drain rules
• ADR-0003: Compiled Invocation Lifecycle - Ray-free session/invocation reducer, absolute deadlines, fallback and replay cutoffs, one-shot output ownership, and bounded cleanup diagnostics
• ADR-0004: Bounded Workflow Progress - Always-bounded summaries, immutable topology pages, normalized latest-state detail, fenced publication, pagination, retention, and legacy snapshot rollout
• ADR-0005: Bounded Workflow Progress Preparation - Selected contract, prototype, and #141 spill-backed production topology adapter for exact one-shot preparation; #142 owns the remaining composite topology/detail lifetime
• Ray Serve Integration Boundary - Deferred ownership, lifecycle, security, and packaging decision
• Changelog - Release history