Get Hacking
Prerequisites
Clone the repository
git clone git@github.com:stacklok/minder.git
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
CLI
The CLI is available in the cmd/cli directory.
go run cmd/cli/main.go --help
APIs
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