Local Build

Requirements

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

• Go (golang.org)
• Node.js (nodejs.org)
• Yarn (yarnpkg.com)

info

If you are building on macOS 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.

After cloning clutch you can run ./tools/preflight-checks.sh, which will check if your local environment has all required dependencies for development.

info

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.

HTTPS

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

SSH

git clone git@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.

make

info

If you receive an error message:

tools/preflight-checks.sh: line 12: realpath: command not found

Then realpath might not be in your $PATH (you can check via which realpath). To resolve this error message on macOS, try running brew link coreutils first, before running make again.

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

Command	Description
make api	Re-generate frontend and backend API objects from changes to .proto files in api/.
make dev	Compile and start the backend on localhost:8080 and a hot-reloading frontend on localhost:3000.
make	Build a unified frontend and backend binary and place it in build/clutch.
make lint-fix	Fix any fixable linting errors. There are also targets for each of API, backend, and frontend, e.g. make frontend-lint-fix.
make test	Run tests. There are also targets for each of backend and frontend, e.g. make backend-test.