Getting Started

To start, get a Git checkout with either of these commands. The 1st one is for public, read-only access. The 2nd one can be used if you have commit rights to the project.

git clone https://projects.blender.org/studio/flamenco.git
git clone [email protected]:studio/flamenco.git

Then follow the steps below to get everything up & running.

1. Installing Go

Most of Flamenco is made in Go.

Install the latest Go release. If you want to know specifically which version in required, check the go.mod file.
Optional: set the environment variable GOPATH to where you want Go to put its packages. Go will use $HOME/go by default.
Ensure $GOPATH/bin is included in your $PATH environment variable. Run go env GOPATH if you’re not sure what path to use.

2. Installing NodeJS

The web UI is built with Vue.js, and Socket.IO for communication with the backend. NodeJS+Yarn is used to collect all of those and build the frontend files.

Linux

It’s recommended to install Node via Snap:

sudo snap install node --classic --channel=18

If you install NodeJS in a different way, it may not be bundled with Yarn. In that case, run:

sudo npm install --global yarn

Windows

Install Node v18 LTS. Be sure to enable the “Automatically install the necessary tools” checkbox.

Then install Yarn via:

npm install --global yarn

macOS

Option 1 (Native install)

Install Node v18 LTS and then install Yarn via:

npm install --global yarn

Option 2 (Homebrew)

Install Node 18 via homebrew:

brew install node@18
brew link node@18

Then install yarn:

brew install yarn

3. Utilities

Building Flamenco requires only a few tools to be installed on your system.

Linux

On Linux only make is necessary, which can be installed via your package manager.

On Debian, and relatives like Ubuntu, run:

sudo apt install make

Windows

Install MingW W64. If in doubt which version to get, grab the x86_64...seh one. You’ll need 7Zip to extract it.

macOS

TODO: write this documentation.

4. Your First Build

Run go run mage.go installDeps to install build-time dependencies. This is only necessary the first time you build Flamenco (or when these dependencies are upgraded, which is rare)

Build the application with go run mage.go build.

You should now have two executables: flamenco-manager and flamenco-worker. Both can be run with the -help CLI argument to see the available options.

See building for more mage targets, for example to run unit tests, enable the race condition checker, and ways to speed up the build process.

5. Get Involved

If you’re interested in helping out with Flamenco development, please read Get Involved!

If you need to change or add any database queries, read through the database section.

Software Design

The Flamenco software follows an API-first approach. All the functionality of Flamenco Manager is exposed via the OpenAPI interface (more info). The web interface is no exception; anything you can do with the web interface, you can do with any other OpenAPI client.

The API can be browsed by following the ‘API’ link in the top-right corner of the Flamenco Manager web interface. That’s a link to http://your.manager.address/api/v3/swagger-ui/
The web interface, Flamenco Worker, and the Blender add-on are all using that same API.

New Features

To add a new feature to Flamenco, these steps are recommended:

Define which changes to the API are necessary, and update the flamenco-openapi.yaml file for this.
Run go generate ./pkg/... to generate the OpenAPI Go code.
Implement any new operations in a minimal way, so that the code compiles (but doesn’t do anything else).
Run make generate to regenerate all the code (so also the JavaScript and Python client, and Go mocks).
Write unit tests that test the new functionality.
Write the code necessary to make the unit tests pass.
Now that you know how it can work, refactor to clean it up.
Send in a pull request!