# Development

- [Getting Started](#getting-started)
- [Checkout repository](#checkout-your-fork)
- [Requirements](#requirements)
- [API Service](#api-service)
* [Running Database](#running-database)
* [Running Database Migration](#database-migration)
* [Adding GitHub OAuth Configuration](#adding-github-oAuth-configuration)
* [Running API Service](#running-api-service)
* [Running Tests](#running-tests)
* [Creating JWT for testing](#creating-jwt-for-testing)
* [API Documentation](#api-documentation)

## Getting Started

1. [Create a GitHub Account][join-github]
1. [Setup GitHub access via SSH][gh-ssh]

## Checkout your fork

To check out this repository:

1. Create your own [fork of this repository][fork-repo]
2. Clone it to your machine:

  git clone [e-mail]:${YOUR_GITHUB_USERNAME}/hub.git
  cd hub

  git remote add upstream [e-mail]:tektoncd/hub.git
  # prevent accidental push to upstream
  git remote set-url --push upstream no-push
  git fetch --all

Adding the upstream remote sets you up nicely for regularly [syncing your fork][sync-fork].

## Requirements

You must install these tools:

1. [`go`][install-go]: The language hub apis are built in.
1. [`git`][install-git]: For source control

You may need to install more tools depending on the way you want to run the hub.

## API Service

### Running database

Two ways to run postgresql database:
- [Install postgresql][install-pg] on your local machine, or
- Run a postgresql container using [docker][install-docker] / [podman][install-podman]

If you have installed postgresql locally, you need to create a `hub` database.

**NOTE:** Use the same configuration mentioned in `.env.dev` or
update `.env.dev` with the configuration you used. The api service
and db migration uses the db configuration from `.env.dev`.

- If you want to run a postgres container, source the `.env.dev` so that
`docker` can use the same database configuration as in `.env.dev` to create a container.

Ensure you are in `hub/api` directory.

  source .env.dev

  docker run -d  --name hub \
    -e POSTGRES_USER=$POSTGRES_USER \
    -e POSTGRES_PASSWORD=$POSTGRES_PASSWORD \
    -e POSTGRES_DB=$POSTGRES_DB \
    -p $POSTGRES_PORT:5432 \
    postgres

### Database Migration

Once the database is up and running, you can run migration to create tables.

Run the following command to run migration

go run ./cmd/db

Wait until the migration completes and logs to show

> DB initialisation successful !!

### Adding GitHub OAuth Configuration

Create a GitHub OAuth. You can find the steps to create it [here][gh-oauth].

Use `http://localhost:8080` as the `Homepage URL` and `Authorization callback URL`.

After creation, add the OAuth Client ID as `GH_CLIENT_ID` and Client Secret as `GH_CLIENT_SECRET` in [.env.dev][env-dev].

For `JWT_SIGNING_KEY`, you can use any random word.

### Running API Service

Once the database is setup and the migration has been run, you can run api service by

go run ./cmd/api

### Running tests

To run the tests, we need a test db.
- If you have installed postgresql, create a `hub_test` database.
- If you are running a container, create `hub_test` database in the same container.

  source .env.dev

  docker exec -it hub bash -c \
    "PGPASSWORD=$POSTGRES_PASSWORD \
     psql -h localhost -p 5432 -U postgres -c 'create database hub_test;'"

Once the `hub_test` database is created, you can run the test using following command:

  go test -p 1 -count=1 -v ./pkg/...

To re-generate the golden files use the below command

go test $(go list -f '{{ .ImportPath }} {{ .TestImports }}' ./... | grep gotest.tools/v3/golden | awk '{print $1}' | tr '\n' ' ') -test.update-golden=true

This will run `go test a/package -test.update-golden=true` on all packages that are importing `gotest.tools/v3/golden`

**NOTE:** `tests` use the database configurations from [test/config/env.test][env-test-file]

### Creating JWT for testing

To create a JWT, Open below URL in a browser.

https://github.com/login/oauth/authorize?client_id=<Add Client ID here>

Add your OAuth Client ID from [.env.dev][env-dev] in place of `<Add Client ID here>`.

It will redirect you to GitHub. Login using your GitHub Credentials and Once you authorize, it will redirect you to `localhost:8080`.

for ex. `http://localhost:8080/?code=32d4a0b4eb6e9fbea731`

Use the `code` from url in `/auth/login` API. It will add you as user in db and return a JWT.

#### JWT with Additional Scopes:

By default, the JWT has only defaut scopes. If you need additional scopes in your JWT then add your GitHub username with required scopes in your local [config.yaml][config-yaml]

And repeat the login process and you will have additonal scopes in JWT.

### API Documentation

API documentation is generated by goa in file [`gen/http/openapi.yaml`][swagger-doc].

Also, you can call the API `/swagger/swagger.json` to get the documentaion.

You can paste file content or API response in [swagger client][swagger].

[join-github]:https://github.com/join
[gh-ssh]:https://help.github.com/articles/connecting-to-github-with-ssh/
[fork-repo]:https://help.github.com/articles/fork-a-repo/
[sync-fork]:https://help.github.com/articles/syncing-a-fork/
[install-go]:https://golang.org/doc/install
[install-goa]:https://github.com/goadesign/goa
[install-git]:https://help.github.com/articles/set-up-git/
[install-pg]: https://www.postgresql.org/docs/12/tutorial-install.html
[install-docker]: https://docs.docker.com/engine/install/
[install-podman]: https://podman.io/getting-started/installation.html
[env-dev]:https://github.com/tektoncd/hub/blob/master/api/.env.dev
[env-test-file]: https://github.com/tektoncd/hub/blob/master/api/test/config/env.test
[gh-oauth]:https://docs.github.com/en/developers/apps/creating-an-oauth-app
[config-yaml]:https://github.com/tektoncd/hub/blob/master/config.yaml
[swagger]:https://editor.swagger.io
[swagger-doc]:https://github.com/tektoncd/hub/blob/master/api/gen/http/openapi.yaml