Setting up a development environment

In order to develop Beneath on your local machine, you need to setup local installations of its dependencies.

It’s a good idea to run each dependency in a separate tab of a single terminal window.

Installing and running dependencies

Run Redis

  • Install with brew install redis
  • Run with redis-server /usr/local/etc/redis.conf

Run Postgres

Install Google Cloud SDK

Follow this tutorial, but first read this: It creates a folder in the directory from which you run the install commands, so make sure you’re in a folder where you won’t delete it by accident (probably home or documents).

Check that everything installed correctly and that you’re in the beneath Google Cloud project by running gcloud projects list (in a new tab). You might also want to check out your ~/.bash_profile to make sure it configured your PATH correctly.

Run Cloud Pubsub emulator

Run Cloud Bigtable emulator

Install VS Code

Running Beneath locally

Configure environment variables

  • Copy configs/example.env into configs/.development.env and configs/.test.env and configure all variables (ask a core team member)

Control backend

  • For development, run with ENV=dev go run cmd/control/main.go
  • If successful, you can access a GraphQL Playground at http://localhost:4000/playground

Gateway backend

  • Run with ENV=dev go run cmd/gateway/main.go
  • If successful, you can ping the gateway at http://localhost:5000/


  • Run with ENV=dev go run cmd/pipeline/main.go

Task queue

  • Run with ENV=dev go run cmd/taskqueue/main.go

Frontend (UI)

  • Go to web/
  • Install dependencies with yarn install (if you don’t have yarn installed, go here)
  • Run dev server with yarn dev