Update setup instructions #152
Conversation
These are mostly automatic changes from Prettier in my editor. I'm committing this before updating local dev setup instructions to make the subsequent diff easier to parse
This updates and restructures/simplifies the local development instructions based on my experience of trying to get the app running locally today. Some of the instructions were outdated; some required a little more guidance I'm still a little unclear on the need/use of the client and webhook secrets - it might be useful to review/flesh out the information regarding their use
|
@danlivings-dxw do let me know if this is very incorrect! |
| @@ -3,91 +3,51 @@ | |||
| Towtruck is an application to aid maintenence of dxw's repos. It aims to make it | |||
| easier to keep on top of which repos need updates applying. | |||
|
|
|||
| Please review the [High Level Design document](/doc/high-level-design.md) if | |||
| this is your first time in the project. | |||
| Be sure to the [High Level Design document](/doc/high-level-design.md) if you're | |||
There was a problem hiding this comment.
I think this is missing a word
| ### GitHub App settings | ||
| ### Setup | ||
|
|
||
| #### Using a test Github App | ||
| 1. Run `script/setup` to set up the app for the first time, including | ||
| installation of dependencies. | ||
|
|
||
| The first step is to register a new app as described | ||
| [here](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app): | ||
| 1. Set environment variables in order for Towtruck to communicate with the | ||
| GitHub API. | ||
|
|
||
| - For **9**, no callback URL is currently required, so this step can be skipped. | ||
| - For **11**, no user authentication is currently required, so this step can be | ||
| skipped. | ||
| - Skip **12** as Towtruck does not use device flow authentication. | ||
| - For **13** and **14**, there is no additional in-app setup performed by | ||
| Towtruck, so these steps can be skipped. | ||
| - Skip **15** as Towtruck does receive GitHub webhooks and should be configured | ||
| to listen for them. | ||
| - For **16**, the webhook URL should be configured to | ||
| `https://<base Towtruck URL>/api/github/webhooks`. Alternatively, for | ||
| development, a [Smee.io](https://smee.io/) channel can be used. | ||
| - For **17**, a strong, randomly-generated secret should be used. | ||
| - For **18**, SSL verification should be used. | ||
| - For **19**, see the **Permissions** section below for a list of required | ||
| permissions. | ||
| - For **20**, see the **Webhooks** section below for a list of required webhooks | ||
| to listen to. | ||
| - For **21**, **Any account** should be used in production when Towtruck is used | ||
| to monitor multiple organisations. Otherwise, **Only this account** should be | ||
| used. | ||
| 1. Open the [GitHub App settings][]. | ||
| 1. Copy the app ID and client ID from the "About" section into your local | ||
| `.env` file. | ||
| 1. Generate a private key in the "Private keys" section. Download the | ||
| generated file, move it to your local repository root folder, rename it to | ||
| `towtruck.private-key.pem` (per the `.gitignore` file), then run | ||
| `script/encode-key towtruck.private-key.pem` from the repository root | ||
| folder. Copy the output of this command as the private key in your local | ||
| `.env` file. | ||
|
|
||
| Once the app is registered, it should be installed to an account to allow | ||
| Towtruck to track it. GitHub have instructions to do this | ||
| [here](https://docs.github.com/en/apps/using-github-apps/installing-your-own-github-app). | ||
| > The `REDIRECT_URL_BASE`, `CLIENT_SECRET`, and `WEBHOOK_SECRET` can remain | ||
| > as their default values. | ||
|
|
||
| ##### Permissions | ||
|
|
||
| Towtruck is still in early development so the exact set of needed permissions | ||
| has not been finalised. | ||
|
|
||
| ##### Webhooks | ||
|
|
||
| Towtruck is still in early development so the exact set of needed webhooks has | ||
| not been finalised. | ||
|
|
||
| #### Using the dxw Github App | ||
|
|
||
| This will use the live data from dxw's repos. Any testing to configuration | ||
| should be performed using a personal test app first. The environment variables | ||
| are available here: | ||
| <https://github.com/organizations/dxw/settings/apps/dxw-towtruck>. You may need | ||
| to ask permission from an owner of the dxw organisation. | ||
|
|
||
| ### Environment variables | ||
|
|
||
| In order for Towtruck to communicate with the GitHub API, it needs several | ||
| pieces of information, configured through environment variables: | ||
| ### Seeding | ||
|
|
||
| - `APP_ID`: The unique numeric ID assigned to the GitHub App. This can be found | ||
| in the dxw-towtruck app settings. | ||
| - `PRIVATE_KEY`: The private key used to sign access token requests. Towtruck | ||
| expects this to be a `.pem` file generated by GitHub in the app settings and | ||
| encoded using Base64. This can be generated from the `.pem` file by running | ||
| `script/encode-key <path-to-pem-file>` in the terminal and copying the output. | ||
| - `CLIENT_ID`: A unique alphanumeric ID assigned to the GitHub App. This can be | ||
| found in the dxw-towtruck app settings. | ||
| - `CLIENT_SECRET`: A token used to authenticate API requests. These are | ||
| generated by GitHub in the dxw-towtruck app settings. | ||
| - `WEBHOOK_SECRET`: A user-defined secret used to authenticate GitHub to | ||
| Towtruck for receiving webhooks. This must be exactly the same as it is | ||
| entered in the app settings on GitHub. | ||
| Run `script/seed` to seed the database using live data from dxw's repositories. | ||
| You can also seed the databse as a final step while bootstrapping using | ||
| `script/bootstrap --seed`. | ||
|
|
||
| ### Seeding | ||
| > This will call the Github API. Requests to this API are rate limited so take | ||
| > care not to to run the script too often. | ||
|
|
||
| Once all the other setup steps have been completed run `script/seed` or | ||
| `script/bootstrap --seed` to seed the data. This will call the Github API which | ||
| is rate limit so take care not to to run the script too often. |
There was a problem hiding this comment.
I think it's worth keeping this information because Towtruck being open source means that it's possible that others may want to deploy their own instance and this documents that. Perhaps the headings/preamble should be updated to make it clearer that our instance is for our stuff and that other people will need to deploy their own instance?
There was a problem hiding this comment.
That's a fair point. I suppose I was thinking this is primarily a dxw thing, given the various mentions of dxw throughout the docs/codebase. There's still value in code being open source even if an app is clearly configured for a specific use case - like the playbook or most of our client work - and this isn't a package/library, but in any case it would probably be useful to retain documentation on how it was set up
Is it specifically the stuff about setting up and using a new GitHub app that you were meaning here? Happy to rework that in - I did start rewriting it based on changes to GitHub's form for creating apps, but then pivoted to streamlining the guidance after our Slack conversation. Could probably reword the second prerequisite and then refer people to a separate section or a separate doc about setting up a GitHub app if using Towtruck for a different organisation
There was a problem hiding this comment.
Also curious how the multi-organisation feature will work, but that's a separate conversation!
There was a problem hiding this comment.
Is it specifically the stuff about setting up and using a new GitHub app that you were meaning here?
I think we should be documenting that, but also the set of permissions and webhooks that we use, as access to these needs to be given to the app in the settings (although I admit we're just using a "TBD" placeholder for these sections at the moment). I think it's also worth having an explanation of what the environment variables do rather than just how to change them, as well.
Could probably reword the second prerequisite and then refer people to a separate section or a separate doc about setting up a GitHub app if using Towtruck for a different organisation
This might be a useful approach to take, so that we can keep the readme to the essentials to getting set up locally.
This updates and restructures/simplifies the local development instructions based on my experience of trying to get the app running locally today. Some of the instructions were outdated; some required a little more guidance
I'm still a little unclear on the need/use of the client and webhook secrets - it might be useful to review/flesh out the information regarding their use