Skip to content

Installation & Configuration

This guide focuses on installing Flamenco while relying on the Blender Cloud service. If you are interested in setting up the entire Flamenco stack on your own infrastructure, you should check out the developer docs, as well as the source code.

We are going to assume that you have a Blender Cloud subscription, and that you already created a project. If you haven't, log in and create a new project.

Here is an overview of the steps required to get Flamenco up an running.

  • Download and install Blender, either on each Worker separately or on a shared storage. Make sure the path is the same on each Worker.
  • Download and configure your Manager
  • Download and configure your Worker
  • Enable your project for Flamenco
  • Configure the Blender Cloud Add-on and start rendering

Note

On Windows, make sure you use mapped drives, so do not use \\SERVER directly. Instead, map it to a drive letter and use that. Furthermore, use forward slashes, so S:/some/path.

This is meant as a step-by-step quick install guide. For more in-depth installation and configuration documents, check out the README.md files and sources of each component.

Flamenco Manager

Flamenco Manager is one of the components that you are responsible fur running on your infrastructure (or on your local machine). The Manager handles the communication between your Workers, which you also run locally, and the Server, which runs on the cloud.blender.org website.

Manager installation

To run Flamenco Manager for the first time, follow these steps:

  1. Optionally install ImageMagick, if you want to show the latest rendered image in the Manager's dashboard, and make sure that the convert command can be found on $PATH. Since there are multiple builds of ImageMagick available, make sure you install the version that is compatible with your render output; for example, get a HDR-enabled build if you render to HDR EXR files.
  2. Download Flamenco Manager for your platform.
  3. Extract the downloaded file.
  4. Run ./flamenco-manager -setup (Linux/macOS) or flamenco-manager.exe -setup (Windows).
  5. Flamenco Manager will give you a list of URLs at which it can be reached. Open the URL that is reachable both for you and the workers.
  6. Link Flamenco Manager to Blender Cloud by following the steps in the web interface.
  7. Configure Flamenco Manager via the web interface; details are described below.
  8. Once you have completed configuration, save the configuration, then restart Flamenco Manager through the web interface. It will now run in normal (i.e. non-setup) mode.

Note

Flamenco Manager uses coloured output for its logging. On Windows by default these colours will not be shown, and instead it will show the control codes literally. This can be solved by adding one key to the Registry, as described in this answer on Stack Overflow.

Manager configuration

Flamenco Manager can be configured via the web interface. Update the variables and path replacement variables for your render farm. If a path contains a space, it should be enclosed in double quotes. Paths should not end in a slash:

  • YES: R: or /Volumes/render
  • NO: R:/ or /Volumes/render/

The following variables should be defined.:

  • blender: should point to the Blender executable.
  • ffmpeg: should point to the FFmpeg executable.
  • job_storage: a two-way variable that should point to the Shaman checkout directory. In other words, it should point to the same directory as the shaman.checkout setting.
  • shaman: a one-way variable that should point to the same directory as the shaman.checkout setting. Since the Shaman is a recent addition, we decided to keep it fully optional and not as integrated as it could be, hence the two variables that basically do the same thing.
  • render: a two-way variable that should point to where rendered output should be saved.

Note

We recommend using forward slashes everywhere, also on Windows.

Example variables

variables:
    blender:
        direction: oneway
        values:
        - audience: all
          platform: darwin
          value: /Applications/blender-2.80/blender.app/Contents/MacOS/blender
        - audience: all
          platform: linux
          value: /home/sybren/bin/blender
        - audience: all
          platform: windows
          value: "C:/Program Files/Blender Foundation/Blender-2.80/blender.exe" --factory-startup
    ffmpeg:
        direction: oneway
        values:
        - audience: all
          platform: windows
          value: "C:/Program Files/FFmpeg/ffmpeg.exe"
        - audience: all
          platform: linux
          value: /usr/bin/ffmpeg
        - audience: all
          platform: darwin
          value: /usr/bin/ffmpeg
    shaman:
        direction: oneway
        values:
        - audience: all
          platform: linux
          value: /shared/flamenco-jobs
    job_storage:
        direction: twoway
        values:
        - audience: all
          platform: linux
          value: /shared/flamenco-jobs
        - audience: all
          platform: windows
          value: 'S:/flamenco-jobs'
        - audience: all
          platform: darwin
          value: /Volume/shared/flamenco-jobs
    render:
        direction: twoway
        values:
        - audience: all
          platform: darwin
          value: /Volume/render
        - audience: all
          platform: linux
          value: /render
        - audience: all
          platform: windows
          value: 'R:'

Two-way variables work as follows. When creating a render job for /shared/flamenco-jobs/projectX/thefile.blend, Flamenco will internally change that to {job_storage}/projectX/thefile.blend. When sending that job to a worker running on Windows, it'll change it to S:/flamenco-jobs/projectX/thefile.blend. In other words, it goes from value to variable, and from variable to value, hence the name "two-way".

Note

We recommend using forward slashes everywhere, also on Windows.

Linking the Manager to a Server

To tell the Manager which Server to use, and to let the Server know that this Manager is available, you have to link your Manager. This can be done by starting Flamenco Manager in setup mode (i.e. run flamenco-manager -setup) and visiting the web interface. There you can provide the Server URL (typically https://cloud.blender.org/) and click on the Link button. Follow the on-screen instructions to complete the link.

Enable project for Flamenco

You can enable for Flamenco any Blender Cloud project you are part of, by going to the main project view (the homepage of a project), clicking on "Edit Project" and then "Flamenco". Alternatively, you can visit the url https://cloud.blender.org/p/<your_project_url>/edit/flamenco. Once in the Flamenco page, click on "Enable for Flamenco". After clicking, some things will happen:

  • You will be able to see your project in Flamenco, where you will manage jobs and tasks.
  • A Flamenco Manager will be attached to the project.

Flamenco Worker

Flamenco Workers are in charge of executing tasks they fetch from the Manager. Workers are written in Python 3.5, so they will run on any system that supports Python 3.5 or newer.

Worker installation and configuration

  1. Download and unzip the latest version of the Worker and extract it.
  2. If you're upgrading from a previous installation: copy flamenco-worker.cfg and flamenco-worker.db to the newly extracted directoy.
  3. Run ./flamenco-worker (macOS and Linux) or flamenco-worker.exe (Windows)

All configuration keys should be placed in the [flamenco-worker] section of the config file. Take a look at:

  • manager_url: Flamenco Manager URL. Leave empty to use UPnP/SSDP to find the Manager on your network automatically.
  • task_types: Space-separated list of task types this worker may execute.
  • task_update_queue_db: filename of the SQLite3 database, holding the queue of task updates to be sent to the Master. If this file does not exist yet, Flamenco Manager will create it.
  • args in the [handler_file] section, to configure where the logs are stored.

Run the Worker with the flamenco-worker command. The Worker will automatically connect to the Manager, negotiate a worker ID and password, and start querying for tasks. The worker ID and password will be stored in $HOME/.flamenco-worker.cfg.

Video Encoding of Image Sequences

Requires Flamenco Manager and Worker version 2.2 or newer.

A Blender Render job can optionally create a video from an image sequence. This allows you to render as an image sequence (allowing each worker to render one or more frames), and as a final step combine those images into a video for easier viewing. However, since this requires FFmpeg, this step is optional and by default Flamenco Server will not generate this video creation task. To enable this, follow these steps:

  • Decide which of your Workers will run the video encoding tasks. This could be all Workers, or one or more dedicated machines.
  • On those workers, update the flamenco_worker.cfg file to have video-encoding in the task_types setting. For example:

    task_types = sleep blender-render file-management exr-merge video-encoding
    
  • Download and install FFmpeg, either on each Worker separately or on a shared storage. Make sure the path is the same on each Worker.

  • Add an ffmpeg variable to your Manager's flamenco_manager.yaml configuration file, which should point to the path where the Workers can find the ffmpeg binary. For example:
    variables:
        blender:
            darwin: /Applications/blender-2.80/blender.app/Contents/MacOS/blender
            linux: /home/sybren/bin/blender
            windows: "C:/Program Files/Blender Foundation/Blender-2.80/blender.exe" --factory-startup
        ffmpeg:
            windows: "C:/Program Files/FFmpeg/ffmpeg.exe"
            linux: /usr/bin/ffmpeg
            darwin: /usr/bin/ffmpeg
    
    • Restart Flamenco Manager and your Workers to activate the change in configuration.
    • Upgrade your Blender Cloud add-on to version 1.9.5 or newer (not yet released at the moment of writing.)

Once these steps have been performed, you can check your Manager configuration on Blender Cloud. Look at the Task Types, and double-check that it shows video-encoding in the list. Once that is there, new Simple Blender Render jobs will automatically use FFmpeg to create videos from file sequences.

Note

We highly recommend ensuring you have exactly the same version of FFmpeg on each worker.