docs/developer-faq.md

   1 # FAQ
   2
   3 Frequently asked questions by developers.
   4
   5 ## Toggle between `beta`/`beta-staging`
   6
   7 `beta-staging` lives on the same domain as `beta`, https://beta.gitter.im/
   8
   9 Here is a bookmarklet for the `beta-staging` toggle (`beta` toggle). It just sets a staging cookie.
  10
  11 ```
  12 javascript:void((function(d){document.cookie='gitter_staging_beta=' + (document.cookie.indexOf('gitter_staging_beta=staged') >= 0 ? 'none' : 'staged') + ';domain=.gitter.im;path=/;expires=' + new Date(Date.now() + 31536000000).toUTCString(); location.reload();})(document));
  13 ```
  14
  15
  16 ## How do I access Gitter over my local network?
  17
  18 #### Update the config
  19
  20 Create `config/config.users-overrides.json` and copy/paste `config/config.dev.json` into your new config.
  21
  22 Adjust all of the `localhost` entries to your local IP in the following sections,
  23
  24  - `web`
  25  - `cdn`
  26  - `webhooks`
  27  - `ws`
  28  - `embed`
  29
  30 ---
  31
  32 Alternatively to copying the whole `config/config.dev.json` over you can just use the relevant parts,
  33
  34 ```json
  35 {
  36   "web": {
  37     "homeurl": "/",
  38     "domain": "192.168.1.135",
  39     "baseserver": "192.168.1.135",
  40     "baseport": "5000",
  41     "basepath": "http://192.168.1.135:5000",
  42     "apiBasePath": "http://192.168.1.135:5000/api",
  43     "badgeBaseUrl" : "http://192.168.1.135:4000"
  44   },
  45   "cdn": {
  46     "use": false,
  47     "hosts": [
  48       "192.168.1.135:5001"
  49     ]
  50   },
  51   "webhooks": {
  52     "basepath": "http://192.168.1.135:3001"
  53   },
  54   "ws": {
  55     "fayeUrl": "http://192.168.1.135:5000/bayeux"
  56   },
  57   "embed": {
  58     "basepath": "http://192.168.1.135:8061"
  59   }
  60 }
  61 ```
  62
  63 #### Update the OAuth callbacks
  64
  65 The OAuth callbacks you created initially have a `localhost:5000` redirect URI
  66 which will just 404 on a separate device when you try to sign in.
  67
  68 Recreate your secrets using your local network IP, see https://gitlab.com/gitterHQ/webapp#configure-service-secrets
  69
  70 Restart the server. You should now be able to access Gitter over your local IP from other devices
  71
  72
  73 ## Debug logging
  74
  75 There are various `debug(...)` statements throughout the code that trace various functions.
  76 If you want to see these log lines, follow the steps below:
  77
  78 ### Backend
  79
  80 For the backend, set the `DEBUG` environment variable,
  81
  82 To show logs for everything you can use `*` [wildcards](https://www.npmjs.com/package/debug#wildcards) in the filter,
  83 ```
  84 DEBUG="*" npm start
  85 ```
  86
  87 Other examples,
  88 ```
  89 DEBUG="gitter:app:permissions:pre-creation:gh-repo-policy-evaluator" npm start
  90 DEBUG="gitter:app:permissions:pre-creation:*" npm start
  91 DEBUG="gitter:app:permissions:pre-creation*" npm start
  92
  93 DEBUG="gitter:app:push-notification-gateway*, gitter:app:group-creation-service*" npm start
  94 ```
  95
  96 To disable, you can set the filter to an empty string,
  97 ```
  98 DEBUG="" npm start
  99 ```
 100
 101 ### Windows
 102
 103 On Windows, the syntax to set an environment variable is a little different,
 104
 105 ```
 106 set DEBUG="gitter:app:push-notification-gateway*"&&npm start
 107 ```
 108
 109 ---
 110
 111 There is also `require('gitter-web-env').logger` which gets logged to file and Kibana(Elasticsearch) in production. These messages are shown in the console/terminal though so you can see them in development.
 112
 113  - `logger.error(...)`
 114  - `logger.warn(...)`
 115  - `logger.info(...)`
 116
 117 ```
 118 logging:level=info npm start
 119 ```
 120
 121 ### Frontend
 122
 123 For the frontend, use `window.localStorage.debug` in the devtools console
 124
 125 To show logs for everything you can use `*` [wildcards](https://www.npmjs.com/package/debug#wildcards) in the filter,
 126 ```js
 127 window.localStorage.debug = '*';
 128 ```
 129
 130 Other examples,
 131 ```js
 132 window.localStorage.debug = 'app:eyeballs:detector';
 133 window.localStorage.debug = 'app:eyeballs:*';
 134 window.localStorage.debug = 'app:eyeballs*';
 135
 136 window.localStorage.debug = 'app:eyeballs:*,app:router-chat*';
 137 ```
 138
 139 To disable, you can set the filter to an empty string,
 140 ```js
 141 window.localStorage.debug = '';
 142 ```
 143
 144
 145 ## View `webpack` bundle visualization (webpack report)
 146
 147 Run the webapp with the `WEBPACK_REPORT` environment variable set to generate the HTML report
 148
 149 macOS/Linux:
 150 ```
 151 WEBPACK_REPORT=1 npm start
 152 ```
 153
 154 Windows:
 155 ```
 156 set WEBPACK_REPORT=1&&npm start
 157 ```
 158
 159 Open `webpack-report/index.html` in your browser
 160
 161
 162
 163 ## Upgrading `@gitterhq/services` to add support for more services (integrations, activity feed)
 164
 165 Recently merged a merge request for [`@gitterhq/services](https://gitlab.com/gitlab-org/gitter/services)? then read on…
 166
 167 ### Prerequisites
 168
 169 Before you proceed, make sure you have done the following:
 170
 171 1. Pushed a tagged release of [`@gitterhq/services`](https://gitlab.com/gitlab-org/gitter/services) to GitLab
 172 2. Updated the [`@gitterhq/services`](https://gitlab.com/gitlab-org/gitter/services) dependency in [`gitter-webhooks-handler`](https://gitlab.com/gitlab-org/gitter/gitter-webhooks-handler) via npm
 173 3. Deployed the new [`gitter-webhooks-handler`](https://gitlab.com/gitlab-org/gitter/gitter-webhooks-handler) (don't worry, your new service won't be accessible unless someone is adept at guessing URLs)
 174
 175 ### Updating `@gitterhq/services`
 176
 177 Once you are sure the above is done, preform the following:
 178
 179 1. Update the version of the `@gitterhq/services` dependency in this project's [`package.json`](package.json)
 180 2. `npm install`
 181 3. `make sprites`
 182 4. Commit your changes and release!
 183
 184
 185 ## Troubleshooting
 186
 187 ### `npm ERR! Maximum call stack size exceeded`
 188
 189 If you are running into `npm ERR! Maximum call stack size exceeded`
 190
 191 ```bash
 192 # Remove nested `node_modules` directories
 193 $ find . -name "node_modules" -exec rm -rf '{}' +
 194
 195 # Remove nested `package-lock.json`
 196 $ find . -name "package-lock.json" -exec rm -rf '{}' +
 197
 198 # Try installing again
 199 $ npm install
 200 ```
 201
 202
 203 ## Miscellaneous tips & tricks
 204
 205 - You can access the homepage even when signed in by using the `?redirect=no` query - https://gitter.im/?redirect=no (http://localhost:5000/?redirect=no)
 206
 207 ### Easily get your Gitter access token
 208
 209 1. You can get your access token by running `troupeContext.accessToken` in the browser's DevTools console
 210
 211 ### Sign in with Gitter access token
 212
 213 1. Open Gitter in a different browser using the `access_token` query parameter, `https://gitter.im/?access_token=<your token>`
 214
 215 If you are using the desktop app, you can follow [these steps to manually authorize](https://gitlab.com/gitlab-org/gitter/desktop/#manually-sign-inauthorize)
 216
 217 ### Invalidate Gitter access token
 218
 219 You can use the handy utility script: `scripts/utils/delete-token.js`
 220
 221 Or you can simply delete the token from the database,
 222
 223 ```sh
 224 $ ssh mongo-replica-01.prod.gitter
 225 $ mongo mongo-replica-01.prod.gitter
 226
 227 > use gitter
 228 > db.oauthaccesstokens.findOne({ token: 'xxx' })
 229 > db.oauthaccesstokens.remove({ token: 'xxx' })
 230 ```
 231
 232
 233 ### Invalidate a GitHub access token
 234
 235 If a GitHub token leaks, we can invalidate with the https://developer.github.com/v3/apps/oauth_applications/#delete-an-app-token API
 236
 237 To grab the `clientId` and `clientSecret` for the request below, use the following links:
 238
 239  - For `user.githubUserToken` -> `Gitter Public Repo Access`: https://github.com/organizations/gitterHQ/settings/applications/70282
 240  - For `user.githubToken` -> `Gitter Private Repo Access`: https://github.com/organizations/gitterHQ/settings/applications/69324
 241
 242 Then fire off the request to delete the GitHub token:
 243 ```
 244 DELETE https://api.github.com/applications/:clientId/token
 245
 246 Basic authentication
 247 Username: <clientId>
 248 Password: <clientSecret>
 249
 250 Accept: application/vnd.github.doctor-strange-preview+json
 251 Content-Type: application/json
 252
 253 Body:
 254 {
 255         "access_token": "xxxtokentorevoke"
 256 }
 257 ```
 258
 259 ## Working with renovate configuration
 260
 261 ### Testing renovate before merging
 262
 263 `renovate` can be run locally
 264
 265 Install it as a global package/command
 266
 267 ```
 268 $ npm i -g renovate
 269 ```
 270
 271 The issue is that renovate reads the config from the repository itself and it always uses default branch (`develop` for webapp). AFAIK there isn't away to point it to a different branch. There is an [issue for interactive MR for config changes](https://github.com/renovatebot/renovate/issues/547) that will remove need for this local/fork testing process.
 272
 273 #### Pointing renovate to your fork
 274
 275 ```
 276 git remote add myfork <url of your fork>
 277 git push renovate-range-strategy myfork
 278 ```
 279
 280 Go to your fork's repository settings (`<myfork url>/-/settings/repository`) and set `renovate-range-strategy` as default branch.
 281
 282 Add `"renovateFork": true,` to your `renovate.json` and push it on top of `myfork/renovate-range-strategy` branch.
 283
 284 Create a token for your user and give it these scopes `api, read_user, read_repository`.
 285
 286 Now you can run renovate
 287
 288 ```
 289 renovate --platform gitlab --dry-run true --print-config true --token "<token>" viktomas/webapp
 290 ```