|
| 1 | +# lagertha |
| 2 | + |
| 3 | +## Requirements |
| 4 | + |
| 5 | +- Nodejs 8 is required |
| 6 | +- MongoDB 3.2 |
| 7 | +- kafka |
| 8 | + |
| 9 | + |
| 10 | +## Install dependencies |
| 11 | + |
| 12 | +```shell |
| 13 | +npm install |
| 14 | +``` |
| 15 | + |
| 16 | +## Source code lint |
| 17 | + |
| 18 | +eslint is used to lint the javascript source code: |
| 19 | + |
| 20 | +```shell |
| 21 | +npm run lint |
| 22 | +``` |
| 23 | + |
| 24 | +## Endpoints |
| 25 | + |
| 26 | +- GET /github/owneruser/login - github owner user login, using GitHub OAuth |
| 27 | +- GET /github/owneruser/callback - github owner user login OAuth callback |
| 28 | +- GET /github/owneruser/teams - github owner user views his/her teams |
| 29 | +- GET /github/teams/:id/registrationurl - github owner user creates a registration URL for his/her team |
| 30 | +- GET /github/teams/registration/:identifier - normal user registers a team via this API, it will do GitHub OAuth |
| 31 | +- GET /github/normaluser/callback - normal user GitHub OAuth callback |
| 32 | + |
| 33 | +- GET /gitlab/owneruser/login - gitlab owner user login, using GitLab OAuth |
| 34 | +- GET /gitlab/owneruser/callback - gitlab owner user login OAuth callback |
| 35 | +- GET /gitlab/owneruser/groups - gitlab owner user views his/her groups |
| 36 | +- GET /gitlab/groups/:id/registrationurl - gitlab owner user creates a registration URL for his/her group |
| 37 | +- GET /gitlab/groups/registration/:identifier - normal user registers a group via this API, it will do GitLab OAuth |
| 38 | +- GET /gitlab/normaluser/callback - normal user GitLab OAuth callback |
| 39 | + |
| 40 | +- GET /tclogin - TopCoder login |
| 41 | +- GET /admin/tcuser - get TopCoder/GitLab/GitHub user mapping |
| 42 | + |
| 43 | +- GET /projects - gets the projects |
| 44 | +- POST /projects - creates a project |
| 45 | +- put /projects - updates the project |
| 46 | +- post /projects/label - create labels in project |
| 47 | +- post /projects/hook - create webhooks in the project repository |
| 48 | +- GET /users/settings - gets the current user's setup |
| 49 | +- GET /users/accessToken - gets the user's access token |
| 50 | + |
| 51 | +## Configuration |
| 52 | + |
| 53 | +Map the localhost to topcoderx.topcoder.com by editing `hosts` file. |
| 54 | + |
| 55 | +The following config parameters are supported, they are defined in `config.js` and can be configured in system environment: |
| 56 | + |
| 57 | + |
| 58 | +| Name | Description | Default | |
| 59 | +| :------------------------------------- | :----------------------------------------: | :------------------------------: | |
| 60 | +| PORT | the port the application will listen on | 80 | |
| 61 | +| API_VERSION | the API version | v1 | |
| 62 | +| LOG_LEVEL | the log level | info | |
| 63 | +| MONGODB_URI | the MongoDB URI | mongodb://localhost:27017/topcoderx | |
| 64 | +| PASSWORD_HASH_SALT_LENGTH | the password hash salt length | 10 | |
| 65 | +| SESSION_SECRET | the session secret | kjsdfkj34857 | |
| 66 | +| GITHUB_CLIENT_ID | the GitHub client id | | |
| 67 | +| GITHUB_CLIENT_SECRET | the GitHub client secret | | |
| 68 | +| GITLAB_CLIENT_ID | the GitLab client id | | |
| 69 | +| GITLAB_CLIENT_SECRET | the GitLab client secret | | |
| 70 | +| WEBSITE | used as base to construct various URLs | http://topcoderx.topcoder.com/ | |
| 71 | + |
| 72 | +| GITLAB_API_BASE_URL | The Gitlab API base URL | https://gitlab.com/api/v4 | |
| 73 | + |
| 74 | +| TC_LOGIN_URL | URL to do TopCoder login | | |
| 75 | +| TC_USER_PROFILE_URL | URL to to call TopCoder API to get profile from token | https://accounts.topcoder.com/member?retUrl=http:%2F%2Ftopcoderx.topcoder.com%2Fapi%2Fv1%2Ftclogin | |
| 76 | +|TOPIC | kafka topic| | |
| 77 | +|KAFKA_OPTIONS | kafka options| | |
| 78 | + |
| 79 | +Other are just constants which don't need to be changed unless modified in code level. |
| 80 | + |
| 81 | +## FE Configs |
| 82 | + |
| 83 | +The frontend config file contains following variables to be configured in `src/front/config.js` |
| 84 | + |
| 85 | +| Name | Description | |
| 86 | +|--------------------------|---------------------------------| |
| 87 | +| ADMIN_TOOL_URL | URL of the admin tool API | |
| 88 | +| COOKIES_SECURE | If true the cookies set by this App will only be transmitted over secure protocols like https. | |
| 89 | +| AUTH_URL | Url of Topcoder auth form | |
| 90 | +| ACCOUNTS_CONNECTOR_URL | Url to TC account connector | |
| 91 | +| JWT_V3_NAME | jwt V3 cookie name | |
| 92 | +| JWT_V2_NAME | jwt V2 cookie name | |
| 93 | +| DIRECT_URL_BASE | URL to be used for constructing the direct url| |
| 94 | +| LABELS | Labels we are going to add to the repository| |
| 95 | +| LABELS_COLOR | The colors for each label above | |
| 96 | +| HOOK_BASE_URL | The generated ngrok url of receiver service| |
| 97 | + |
| 98 | +## GitHub OAuth App Setup |
| 99 | + |
| 100 | +- login into github.com |
| 101 | +- click the upper right avatar, then click `Settings` |
| 102 | +- click the left panel --> Developer settings --> OAuth Apps |
| 103 | +- click the `Register a new application`, fill in the fields, |
| 104 | + note that the `Authorization callback URL` should be the deployed web site, |
| 105 | + for local deployment, it should be `http://topcoderx.topcoder.com` |
| 106 | +- after creating the OAuth app, you can see its client id and client secret, |
| 107 | + these should be set to GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET environment variables |
| 108 | + |
| 109 | +## GitLab OAuth App Setup |
| 110 | + |
| 111 | +- login into gitlab.com |
| 112 | +- click the upper right avatar, then click `Settings` |
| 113 | +- click the `Applications` tab |
| 114 | +- enter application name, e.g. `Topcoder-x` |
| 115 | +- for Redirect URI, enter two callback URLs, one callback URL per line, so there are two lines: |
| 116 | + http://topcoderx.topcoder.com/api/v1/gitlab/owneruser/callback |
| 117 | + http://topcoderx.topcoder.com/api/v1/gitlab/normaluser/callback |
| 118 | +- for Scopes, check the `api` and `read_user`, the `api` is for owner user, the `read_user` is for normal user |
| 119 | +- finally click `Save application` to save the OAuth app, then you will see its generated Application Id and Secret, |
| 120 | + these should be set to GITLAB_CLIENT_ID and GITLAB_CLIENT_SECRET environment variables |
| 121 | + |
| 122 | +## Local Setup |
| 123 | + |
| 124 | +```shell |
| 125 | +npm run serve |
| 126 | +``` |
| 127 | + |
| 128 | +Server should be started at port 80. |
| 129 | + |
| 130 | +## Postman |
| 131 | + |
| 132 | +Import docs/Ragnar.postman_collection.json and docs/Ragnar.postman_environment.json to Postman. |
| 133 | + |
| 134 | +After admin login, the admin token is automatically set to ADMIN-TOKEN environment variable, |
| 135 | +then you may run the `Save GitHub User` and `Save GitLab User` tests to create owner user of your GitHub/GitLab usernames, |
| 136 | +note that you must modify the request body username to use your GitHub/GitLab user names. |
| 137 | +For the `Get User Mapping` test, you may quety mapping by providing either topcoderUsername, githubUsername or gitlabUsername. |
| 138 | + |
| 139 | +## Verification |
| 140 | + |
| 141 | +- run `npm serve` to start the app |
| 142 | +- go to topcoderx.topcoder.com and it will redirect to Topcoder login page, after successful login it will redirect back to Topcoder x app. |
| 143 | +- go to settings by clicking username at top right corner |
| 144 | +- setup both git provider to authorize topcoder-x to manage your repo on behalf of you |
| 145 | +- go to project management and create/edit projects, create hook and label |
| 146 | +- go to git access control menu and check list of groups have authorized |
| 147 | +- click get link button to get the shareable link which can be used by topcoder member to self assign to the repository. |
| 148 | + |
| 149 | +## Heroku Deployment |
| 150 | +Follow the below steps to deploy the app to heroku |
| 151 | +1. `heroku login` |
| 152 | +2. `heroku create` |
| 153 | +3. `heroku config:set NPM_CONFIG_PRODUCTION=false` so that heroku will install dev dependencies |
| 154 | +5. `git push heroku master` or `git push heroku develop:master` to deploy develop branch |
| 155 | +6. `heroku open` to load the app on browser |
| 156 | + |
| 157 | +NOTE: Once environment variable are changed in heroku please run |
| 158 | +`heroku run npm run build` |
0 commit comments