flamenco/README.md

Flamenco

Open-source render management system for Blender

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. 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

# 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:

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
• Quick Start Guide: flamenco.blender.org/usage/quickstart
• Usage Documentation: flamenco.blender.org/usage
• Development Guide: 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 for build instructions and contribution guidelines.

License

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