Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
230 lines (155 loc) · 7.35 KB

DEVELOPMENT.md

File metadata and controls

230 lines (155 loc) · 7.35 KB
Raw

Development

Getting Started

  1. Create a GitHub Account
  2. Setup GitHub access via SSH

Checkout your fork

To check out this repository:

  1. Create your own fork of this repository
  2. Clone it to your machine:
  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.

Requirements

You must install these tools:

  1. go: The language hub apis are built in.
  2. git: For source control
  3. node: To publish and install packages to and from the public npm registry

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:

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 (Optional)

Create a GitHub OAuth. You can find the steps to create it here with Authorization callback URL as http://localhost:4200
Create a Gitlab OAuth. You can find the steps to create it here with Authorization callback URL as http://localhost:4200/auth/gitlab/callback
Create a BitBucket OAuth. You can find the steps to create it here with Authorization callback URL as http://localhost:4200

After creation, add the OAuth Client ID as
OAuth Client ID GH_CLIENT_ID and Client Secret as GH_CLIENT_SECRET for Github
OAuth Client ID GL_CLIENT_ID and Client Secret as GL_CLIENT_SECRET for Gitlab
OAuth Client ID BB_CLIENT_ID and Client Secret as BB_CLIENT_SECRET for BitBucket
in .env.dev.

For JWT_SIGNING_KEY, you can use any random word.

For ACCESS_JWT_EXPIRES_IN and REFRESH_JWT_EXPIRES_IN you can set the time as per your convenience. Example 15m, 10y.

For AUTH_BASE_URL, use the http://localhost:4200

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

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

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.

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

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

UI

Running UI

Ensure you are in hub/ui directory

Run the following command to install the dependencies

npm install

To start the application run the following command

npm start

You will see Hub running at http://localhost:3000

Running UI Tests

Run the following command to run all the tests

npm test