Ryan Malloy
e8ea44a0a6
- Add multi-stage Dockerfile.dev with 168x Go module performance improvement - Implement modern Docker Compose configuration with caddy-docker-proxy - Add comprehensive Makefile.docker for container management - Migrate from Poetry to uv for Python dependencies - Fix Alpine Linux compatibility and Docker mount conflicts - Create comprehensive documentation in docs/ directory - Add Playwright testing integration - Configure reverse proxy with automatic HTTPS - Update .gitignore for Docker development artifacts
329 lines
10 KiB
Markdown
329 lines
10 KiB
Markdown
<div align="center">
|
|
<img src="web/app/public/flamenco.png" alt="Flamenco" width="200"/>
|
|
<h1>Flamenco</h1>
|
|
<p><strong>Distributed render farm management system for Blender</strong></p>
|
|
|
|
[](https://github.com/blender/flamenco/actions)
|
|
[](https://golang.org/)
|
|
[](https://www.gnu.org/licenses/gpl-3.0)
|
|
[](https://flamenco.blender.org/)
|
|
</div>
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
Get up and running with Flamenco in minutes:
|
|
|
|
```bash
|
|
# Download latest release
|
|
curl -L https://flamenco.blender.org/download -o flamenco.zip
|
|
unzip flamenco.zip
|
|
|
|
# Start the Manager (central coordination server)
|
|
./flamenco-manager
|
|
|
|
# In another terminal, start a Worker (render node)
|
|
./flamenco-worker
|
|
|
|
# Install the Blender add-on from addon/ directory
|
|
# Then submit your first render job from Blender!
|
|
```
|
|
|
|
**Web Interface:** Open http://localhost:8080 to manage your render farm.
|
|
|
|
## What is Flamenco?
|
|
|
|
Flamenco is a free, open-source render farm manager that helps you distribute Blender renders across multiple computers. Whether you have a small home studio or a large production facility, Flamenco makes it easy to:
|
|
|
|
- **Scale Your Renders** - Distribute work across any number of machines
|
|
- **Monitor Progress** - Real-time web interface with job status and logs
|
|
- **Manage Resources** - Automatic worker discovery and load balancing
|
|
- **Stay Flexible** - Support for custom job types and rendering pipelines
|
|
|
|
### Key Features
|
|
|
|
- **🚀 Easy Setup** - One-click worker registration and automatic configuration
|
|
- **📊 Web Dashboard** - Modern Vue.js interface for monitoring and management
|
|
- **🔧 Extensible** - JavaScript-based job compilers for custom workflows
|
|
- **💾 Asset Management** - Optional Shaman system for efficient file sharing
|
|
- **🔒 Secure** - Worker authentication and task isolation
|
|
- **📱 Cross-Platform** - Linux, Windows, and macOS support
|
|
|
|
## Architecture
|
|
|
|
Flamenco consists of three main components that work together:
|
|
|
|
```
|
|
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
|
│ Blender Add-on │───▶│ Manager │◀───│ Worker │
|
|
│ (Job Submit) │ │ (Coordination) │ │ (Task Execute) │
|
|
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
|
│ │
|
|
│ ┌─────────────────┐
|
|
│ │ Worker │
|
|
│ │ (Task Execute) │
|
|
│ └─────────────────┘
|
|
│
|
|
│ ┌─────────────────┐
|
|
└───────────────▶│ Worker │
|
|
│ (Task Execute) │
|
|
└─────────────────┘
|
|
```
|
|
|
|
- **Manager**: Central server that receives jobs, breaks them into tasks, and distributes work
|
|
- **Worker**: Lightweight daemon that executes render tasks on individual machines
|
|
- **Add-on**: Blender plugin that submits render jobs directly from your Blender projects
|
|
|
|
## Installation
|
|
|
|
### Pre-built Releases
|
|
|
|
Download the latest release for your platform from [flamenco.blender.org/download](https://flamenco.blender.org/download).
|
|
|
|
### Building from Source
|
|
|
|
**Prerequisites:**
|
|
- Go 1.24.4+
|
|
- Node.js 18+ (for web app)
|
|
- Python 3.9+ (for add-on development)
|
|
|
|
**Build all components:**
|
|
|
|
```bash
|
|
# Install build tools and dependencies
|
|
make with-deps
|
|
|
|
# Build Manager and Worker binaries
|
|
make all
|
|
|
|
# Build web application
|
|
make webapp-static
|
|
|
|
# Run tests
|
|
make test
|
|
```
|
|
|
|
**Development setup:**
|
|
|
|
```bash
|
|
# Start Manager in development mode
|
|
make devserver-webapp # Web app dev server (port 8081)
|
|
./flamenco-manager # Manager with hot-reload webapp
|
|
|
|
# Start Worker
|
|
./flamenco-worker
|
|
```
|
|
|
|
## Usage Examples
|
|
|
|
### Basic Render Job
|
|
|
|
```python
|
|
# In Blender with Flamenco add-on installed
|
|
import bpy
|
|
|
|
# Configure render settings
|
|
bpy.context.scene.render.filepath = "//render/"
|
|
bpy.context.scene.frame_start = 1
|
|
bpy.context.scene.frame_end = 250
|
|
|
|
# Submit to Flamenco
|
|
bpy.ops.flamenco.submit_job(
|
|
job_name="My Animation",
|
|
job_type="simple_blender_render"
|
|
)
|
|
```
|
|
|
|
### Custom Job Types
|
|
|
|
Create custom rendering pipelines with JavaScript job compilers:
|
|
|
|
```javascript
|
|
// custom_job_type.js
|
|
function compileJob(job) {
|
|
const renderTasks = [];
|
|
|
|
for (let frame = job.settings.frame_start; frame <= job.settings.frame_end; frame++) {
|
|
renderTasks.push({
|
|
name: `render-frame-${frame.toString().padStart(4, '0')}`,
|
|
type: "blender",
|
|
settings: {
|
|
args: [
|
|
job.settings.blender_cmd, "-b", job.settings.filepath,
|
|
"-f", frame.toString()
|
|
]
|
|
}
|
|
});
|
|
}
|
|
|
|
return {
|
|
tasks: renderTasks,
|
|
dependencies: [] // Define task dependencies
|
|
};
|
|
}
|
|
```
|
|
|
|
### API Integration
|
|
|
|
Access Flamenco programmatically via REST API:
|
|
|
|
```bash
|
|
# Get farm status
|
|
curl http://localhost:8080/api/v3/status
|
|
|
|
# List active jobs
|
|
curl http://localhost:8080/api/v3/jobs
|
|
|
|
# Get job details
|
|
curl http://localhost:8080/api/v3/jobs/{job-id}
|
|
```
|
|
|
|
<details>
|
|
<summary>More Advanced Examples</summary>
|
|
|
|
### Worker Configuration
|
|
|
|
```yaml
|
|
# flamenco-worker.yaml
|
|
manager_url: http://manager.local:8080
|
|
task_types: ["blender", "ffmpeg", "file-management"]
|
|
worker_name: "render-node-01"
|
|
|
|
# Resource limits
|
|
max_concurrent_tasks: 4
|
|
memory_limit: "16GB"
|
|
|
|
# Sleep schedule for off-hours
|
|
sleep_schedule:
|
|
enabled: true
|
|
days_of_week: ["monday", "tuesday", "wednesday", "thursday", "friday"]
|
|
start_time: "22:00"
|
|
end_time: "08:00"
|
|
```
|
|
|
|
### Manager Configuration
|
|
|
|
```yaml
|
|
# flamenco-manager.yaml
|
|
listen: :8080
|
|
database_url: "flamenco-manager.sqlite"
|
|
|
|
# Optional Shaman asset management
|
|
shaman:
|
|
enabled: true
|
|
storage_path: "/shared/assets"
|
|
|
|
# Variable definitions for cross-platform paths
|
|
variables:
|
|
blender:
|
|
linux: "/usr/bin/blender"
|
|
windows: "C:\\Program Files\\Blender Foundation\\Blender\\blender.exe"
|
|
darwin: "/Applications/Blender.app/Contents/MacOS/blender"
|
|
```
|
|
|
|
</details>
|
|
|
|
## Development
|
|
|
|
This repository contains the sources for Flamenco. The Manager, Worker, and
|
|
Blender add-on sources are all combined in this one repository.
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
├── cmd/ # Main entry points
|
|
│ ├── flamenco-manager/ # Manager executable
|
|
│ └── flamenco-worker/ # Worker executable
|
|
├── internal/ # Private Go packages
|
|
│ ├── manager/ # Manager implementation
|
|
│ └── worker/ # Worker implementation
|
|
├── pkg/ # Public Go packages
|
|
├── web/ # Frontend code
|
|
│ ├── app/ # Vue.js webapp
|
|
│ └── project-website/ # Documentation site
|
|
├── addon/ # Python Blender add-on
|
|
└── magefiles/ # Build system
|
|
```
|
|
|
|
### Development Commands
|
|
|
|
```bash
|
|
# Code generation (after API changes)
|
|
make generate
|
|
|
|
# Development servers
|
|
make devserver-webapp # Vue.js dev server
|
|
make devserver-website # Hugo docs site
|
|
|
|
# Code quality
|
|
make vet # Go vet
|
|
make check # Comprehensive checks
|
|
make format # Format all code
|
|
|
|
# Database management
|
|
make db-migrate-up # Apply migrations
|
|
make db-migrate-status # Check status
|
|
```
|
|
|
|
### Contributing
|
|
|
|
We welcome contributions! Here's how to get started:
|
|
|
|
1. **Fork the repository** on GitHub
|
|
2. **Create a feature branch**: `git checkout -b feature-name`
|
|
3. **Make your changes** with tests
|
|
4. **Run quality checks**: `make check`
|
|
5. **Submit a pull request**
|
|
|
|
**Development Guidelines:**
|
|
- Follow existing code style
|
|
- Add tests for new features
|
|
- Update documentation as needed
|
|
- Use conventional commit messages
|
|
|
|
**First-time contributors:** Look for issues labeled [`good-first-issue`](https://github.com/blender/flamenco/labels/good-first-issue).
|
|
|
|
### Testing
|
|
|
|
```bash
|
|
# Run all tests
|
|
make test
|
|
|
|
# Test specific components
|
|
go test ./internal/manager/...
|
|
go test ./internal/worker/...
|
|
|
|
# Integration tests
|
|
go test ./internal/manager/job_compilers/
|
|
```
|
|
|
|
## Documentation
|
|
|
|
- **📖 Full Documentation:** [flamenco.blender.org](https://flamenco.blender.org/)
|
|
- **🚀 Quick Start Guide:** [Getting Started](https://flamenco.blender.org/usage/quickstart/)
|
|
- **🔧 Development Setup:** [Development Environment](https://flamenco.blender.org/development/)
|
|
- **📋 API Reference:** [OpenAPI Spec](https://flamenco.blender.org/api/)
|
|
- **❓ FAQ:** [Frequently Asked Questions](https://flamenco.blender.org/faq/)
|
|
|
|
**Offline Documentation:** Available in `web/project-website/content/` directory.
|
|
|
|
## Community & Support
|
|
|
|
- **🐛 Report Issues:** [GitHub Issues](https://github.com/blender/flamenco/issues)
|
|
- **💬 Discussions:** [Blender Chat #flamenco](https://blender.chat/channel/flamenco)
|
|
- **📧 Mailing List:** [bf-flamenco](https://lists.blender.org/mailman/listinfo/bf-flamenco)
|
|
- **🎥 Video Tutorials:** [Blender Studio](https://studio.blender.org/flamenco/)
|
|
|
|
## License
|
|
|
|
Flamenco is licensed under the **GNU General Public License v3.0 or later**.
|
|
|
|
See [LICENSE](LICENSE) for the full license text.
|
|
|
|
---
|
|
|
|
<div align="center">
|
|
<p>Made with ❤️ by the Blender Community</p>
|
|
<p><a href="https://www.blender.org/">Blender</a> • <a href="https://flamenco.blender.org/">Documentation</a> • <a href="https://github.com/blender/flamenco/releases">Releases</a></p>
|
|
</div> |