Skip to main content

Get Hacking


Clone the repository

git clone

Build the application

make build

Run the application

Note that the application requires a database to be running. This can be achieved using docker-compose:

services="postgres keycloak migrateup" make run-docker

Then run the application

bin/minder-server serve

Or direct from source

go run cmd/server/main.go serve

The application will be available on https://localhost:8080 and gRPC on https://localhost:8090.

Run the tests

make test

Install tools

You may bootstrap the whole development environment, which includes initializing the config.yaml file with:

make bootstrap


The CLI is available in the cmd/cli directory.

go run cmd/cli/main.go --help


The APIs are defined in protobuf here.

An OpenAPI / swagger spec is generated to here

It can be accessed over gRPC or HTTP using gprc-gateway.

How to generate protobuf stubs

We use buf to generate the gRPC / HTTP stubs (both protobuf and openAPI).

To build the stubs, run:

make clean-gen
make gen

Database migrations and tooling

Minder uses sqlc to generate Go code from SQL.

The main configuration file is sqlc.yaml.

To make changes to the database schema, create a new migration file in the database/migrations directory.

Add any queries to the database/queries/sqlc.sql file.

To generate the Go code, run:

make sqlc

Users will then need to peform a migration

make migrateup
make migratedown

Viper configuration

Minder uses viper for configuration.

An example configuration file is config/config.yaml.example.

Most values should be quite self-explanatory.

Before running the app, please copy the content of config/config.yaml.example into $PWD/config.yaml file, and modify to use your own settings.

Keycloak configuration for social login (GitHub)

Create an OAuth2 application for GitHub here. Select New OAuth App and fill in the details. The callback URL should be http://localhost:8081/realms/stacklok/broker/github/endpoint. Create a new client secret for your OAuth2 client.

Using the client ID and client secret you created above, enable GitHub login on Keycloak by running the following command:

make KC_GITHUB_CLIENT_ID=<client_id> KC_GITHUB_CLIENT_SECRET=<client_secret> github-login