Continuous integration	License

Mediator

Mediator is a platform to manage the security of your software supply chain.

It is currently in early development.

Get Hacking (Development)

Prerequisites

• Go
• Docker or..
• Podman
• Docker Compose or..
• Podman Compose

Once you have these and have cloned the repository, you'll also need to install the other tools and make sure that $HOME/go/bin is in your PATH.

Clone the repository

git clone git@github.com:stacklok/mediator.git

Build the application

make build

Initialize the configuration

Before running the makefile targets, you need to initialize the application's configuration file. You may do so by doing

cp config/config.yaml.example config.yaml

Alernatively, you may simply bootstrap the whole development environment, which includes initializing this file with:

make bootstrap

Initialize the database

Both the mediator application and the tests need a Postgres database to be running. For development use, the standard defaults should suffice:

docker-compose up -d postgres
make migrateup

Run the application

You will need to initialize the database before you can start the application. Then run the application:

bin/mediator-server serve

Or direct from source

make run-server

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

Running the server under Compose:

NOTE: the command will be either docker-compose or podman-compose, depending on which tool you installed. You'll need to install the ko tool do the build and run.

# The repo to push to; "ko.local" is a special string meaning your local Docker repo
KO_DOCKER_REPO=ko.local
# ko adds YAML document separators at the end of each document, which docker-compose doesn't like
docker-compose -f <(ko resolve -f docker-compose.yaml | sed 's/^---$//') up

Run the tests

Note that you need to have started the database and loaded the schema before running the tests:

make test

You can alse use make cover to check coverage.

Install tools

make bootstrap

CLI

The CLI is available in the cmd/cli directory.

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

To start with, you will need to run cli auth login -u root -p P4ssw@rd matching the password bootstrapped from the database initialization

APIs

API Doc here

The APIs are defined in protobuf here.

An OpenAPI / swagger spec is generated to JSON

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 gen

Database migrations and tooling

Mediator 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

Mock

Mediator uses mockgen to generate mocks.

To generate the mocks, run:

mockgen -package mockdb -destination database/mock/store.go github.com/stacklok/mediator/pkg/db Store

Configuration

Mediator 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.

Initial setup / Getting started

Login

First, login with the default password for the database:

go run ./cmd/cli/main.go auth login -u root -p P4ssw@rd

This will result in the following prompt:

You have been successfully logged in. Your access credentials saved to /var/home/jaosorior/.config/mediator/credentials.json
Remember that if that's your first login, you will need to update your password using the user update --password command

At this point, you should update the password:

go run ./cmd/cli/main.go user update -p f00b@r123 -c f00b@r123

And subsequently log in again with your new password

go run ./cmd/cli/main.go auth login -u root -p 'f00b@r123'

Enroll provider

First, you'll need to enroll your first provider. Before doing this, make sure to set up a GitHub OAuth2 Application, and fill in the appropriate settings in your config.yaml file.

You may create an OAuth2 application here. Select New OAuth App and fill in the details. The callback URL should be http://localhost:8080/api/v1/auth/callback/github/cli. Create a new client secret and fill in the client_id and client_secret in your config.yaml file.

Once the Application is registered and the configuration is set, you can enroll the provider:

go run ./cmd/cli/main.go provider enroll -n github

This will take you through the OAuth2 flow and will result in the provider filling up the repositories table with the repositories you have access to.

Register repositories

Now that you've granted the GitHub app permissions to access your repositories, you can register them:

go run ./cmd/cli/main.go repo register -n github -g 1

You're probably wondering why you need to pass the -g flag. This is because the repositories are registered under a group. This is to allow for multiple repositories to be registered under the same group. In the future, you might create different groups for different purposes. For example, you might have a group for your personal repositories, and another group for your work repositories.

Once you've registered the repositories, the mediator server will listen for events from GitHub and will automatically create the necessary webhooks for you.