# 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:
```shell
git clone git@github.com:${YOUR_GITHUB_USERNAME}/hub.git
cd hub
git remote add upstream git@github.com: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.
```bash
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
```bash
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
```bash
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.
```bash
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:
```bash
go test -p 1 -count=1 -v ./pkg/...
```
To re-generate the golden files use the below command
This will run `go test a/package -test.update-golden=true` on all packages that are importing `gotest.tools/v3/golden`
```bash
go test $(go list -f '{{ .ImportPath }} {{ .TestImports }}' ./... | grep gotest.tools/v3/golden | awk '{print $1}' | tr '\n' ' ') -test.update-golden=true
```
**NOTE:** `tests` use the database configurations from [test/config/env.test][env-test-file]
### Creating JWT for testing
To create a JWT, create a HTML file adding below code
```html
<!DOCTYPE html>
<html>
<body>
<a href="https://github.com/login/oauth/authorize?client_id=<Add Client ID here>">
Login with github
</a>
</body>
</html>
````
Add your OAuth Client ID from [.env.dev][env-dev] in HTML file in place of `<Add Client ID here>` and Save it.
Open the HTML file, click on `Login with github` It will redirect you to GitHub. Once you authorize, it will redirect you to url localhost.
for ex. `http://localhost:8080/?code=32d4a0b4eb6e9fbea731`
Use the `code` from url in `/auth/login` API. It will create a 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
Sign in with Wallet
Connect another wallet