Local Build


In order to build Clutch, the following tools are required:


If you are building on OSX you'll need to install coreutils. This is easiest with homebrew.

brew install coreutils

Homebrew package manager is recommended for macOS users to manage these dependencies.


If running Clutch in a Docker container is preferred, see the Docker docs.

Building Clutch

1. Clone

Start by cloning the Clutch repository and entering into the source directory.

git clone https://github.com/lyft/clutch
cd clutch

2. Build

Run make to build a combined frontend and backend binary. The frontend is configured at build time by clutch.config.js.


3. Run

Launch Clutch with back-end configuration clutch-config.yaml.

./build/clutch -c backend/clutch-config.yaml

4. Use

🎉 Clutch should now be accessible from localhost:8080 in the browser.

Clutch Landing Page Screenshot

Clutch may have external dependencies, to run Clutch with mocked dependencies see Mock Gateway.

Additional Build Targets

Clutch includes a comprehensive Makefile to simplify the execution of commands related to compiling, testing, and executing tools in the project.

The default target, e.g. running make in the root of Clutch, builds the frontend first and then packages it into the backend using vfsgen.

The most commonly used make targets that every Clutch developer should know:

make apiRe-generate frontend and backend API objects from changes to .proto files in api/.
make devCompile and start the backend on localhost:8080 and a hot-reloading frontend on localhost:3000.
makeBuild a unified frontend and backend binary and place it in build/clutch.
make lint-fixFix any fixable linting errors. There are also targets for each of API, backend, and frontend, e.g. make frontend-lint-fix.
make testRun tests. There are also targets for each of backend and frontend, e.g. make backend-test.