flamenco/README.md

# Flamenco

**Open-source render management system for Blender**

<div align="center">
  
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Go Report Card](https://goreportcard.com/badge/projects.blender.org/studio/flamenco)](https://goreportcard.com/report/projects.blender.org/studio/flamenco)

</div>

Flamenco is a free, open-source render management system developed by Blender Studio. Take control of your computing infrastructure and efficiently manage Blender render jobs across multiple machines with minimal configuration required.

## Quick Start

### 1. Download Flamenco
Download the appropriate package for your platform from [flamenco.blender.org/download](https://flamenco.blender.org/download/). Each download contains both Manager and Worker executables.

**Current stable version: 3.7**

### 2. Set Up Shared Storage
Create a shared storage directory accessible by all computers in your render farm:
- **Network file sharing** between all computers
- **Windows**: Use drive letters only (UNC paths like `\\server\share` are not supported)
- **Cloud storage**: Not supported by Flamenco

### 3. Install Blender Consistently
Ensure Blender is installed in the same location across all rendering computers for path consistency.

### 4. Configure Manager
1. Run `flamenco-manager` executable
2. Use the Setup Assistant to configure your render farm
3. Access the web interface to monitor jobs and workers

### 5. Set Up Blender Add-on
1. Download the Blender add-on from the Manager's web interface
2. Install and configure it with your Manager's address
3. Save your blend files in the shared storage location

### 6. Submit Renders
Submit render jobs directly through Blender's Output Properties panel using the Flamenco add-on.

## Key Features

- **Zero Configuration**: Requires almost no setup for production use
- **Cross-Platform**: Windows, Linux, and macOS (including Apple Silicon)
- **Self-Hosted**: Complete control over your data and infrastructure
- **Job Types**: Customizable job types defined via JavaScript compiler scripts
- **Web Interface**: Monitor and manage renders through a modern Vue.js web UI
- **Variable System**: Multi-platform variables for handling different file paths
- **Asset Management**: Optional Shaman storage system for efficient asset sharing
- **Worker Management**: Tags, sleep scheduling, and task assignment
- **Real-time Updates**: Socket.io for live job and task status updates

## Architecture

Flamenco consists of three main components:

- **Flamenco Manager**: Central coordination server built with Go and SQLite
- **Flamenco Worker**: Task execution daemon that runs on rendering machines
- **Blender Add-on**: Python plugin for submitting render jobs from within Blender

### Job Types & Variables

- **Job Types**: Defined by JavaScript compiler scripts that convert jobs into executable tasks
- **Variables**: Platform-specific configuration (e.g., different Blender paths for Windows/Linux/macOS)
- **Task Types**: Standard types include `blender`, `ffmpeg`, `file-management`, and `misc`

## Development

This repository contains the complete Flamenco source code in a unified Go monorepo.

### Quick Development Setup

```bash
# Clone the repository
git clone https://projects.blender.org/studio/flamenco.git
cd flamenco

# Install dependencies (requires Go latest + Node v22 LTS + Yarn)
go run mage.go installDeps

# Build Flamenco
go run mage.go build

# Or using Make wrapper
make with-deps    # Install generators and build everything
make all          # Build manager and worker binaries
```

### Build System
Flamenco uses **Mage** as the primary build tool, wrapped by a Makefile:

```bash
make webapp-static         # Build Vue.js webapp and embed in manager
make test                  # Run all tests
make generate              # Generate code (Go, Python, JavaScript APIs)
make format                # Format all code
```

### Project Structure
- `cmd/` - Main entry points for binaries
- `internal/manager/` - Manager-specific code (job scheduling, API, persistence)
- `internal/worker/` - Worker-specific code (task execution)
- `pkg/` - Public Go packages (API, utilities, shared components)
- `web/app/` - Vue.js 3 webapp with TypeScript and Vite
- `addon/` - Python Blender add-on with Poetry dependency management
- `magefiles/` - Mage build system implementation

### Development Principles
- **API-First**: All functionality exposed via OpenAPI interface
- **Code Generation**: Auto-generated API clients for Python and JavaScript
- **Modern Stack**: Go backend, Vue.js 3 frontend, SQLite database

## System Requirements

### Shared Storage Requirements
Network-accessible storage for all render farm computers with three approaches:
1. **Direct shared storage**: All computers access the same network location
2. **Job copies**: Files copied to local storage before rendering  
3. **Shaman**: Content-addressable storage system for asset deduplication

**Important limitations:**
- Windows: Drive letter mapping required (no UNC paths)
- Cloud storage services are not supported
- Assumes immediate file availability across all workers

### Platform Support
- **Windows**: 64-bit Windows with drive letter access
- **Linux**: 64-bit distributions
- **macOS**: Intel and Apple Silicon supported

## Documentation

- **Main Website**: [flamenco.blender.org](https://flamenco.blender.org/)
- **Quick Start Guide**: [flamenco.blender.org/usage/quickstart](https://flamenco.blender.org/usage/quickstart/)
- **Usage Documentation**: [flamenco.blender.org/usage](https://flamenco.blender.org/usage/)
- **Development Guide**: [flamenco.blender.org/development](https://flamenco.blender.org/development/)
- **Offline Documentation**: Available in `web/project-website/content/` directory

## Contributing

Flamenco is developed by Blender Studio and welcomes contributions from the community. See the [development documentation](https://flamenco.blender.org/development/getting-started/) for build instructions and contribution guidelines.

## License

Flamenco is licensed under the GNU General Public License v3.0 or later.