add basic READMEs #14
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -1,100 +1,132 @@ | ||||||
| # Coder Backstage Plugin | ||||||
|
|
||||||
| Create and manage [Coder workspaces](https://coder.com/docs/v2/latest) from Backstage. | ||||||
|
|
||||||
| ## Screenshots | ||||||
|
|
||||||
|  | ||||||
|
|
||||||
|  | ||||||
|
|
||||||
| ## Features | ||||||
|
|
||||||
| - Users link their Coder accounts with Backstage via tokens | ||||||
| - Associate Coder workspaces with catalog items in Backstage | ||||||
| - Workspace list component for viewing and managing workspaces | ||||||
| - Full Coder API access for custom plugins & integrations | ||||||
bpmct marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
|
||||||
| ## Setup | ||||||
|
|
||||||
| This assumes you already have a [Coder](https://github.com/coder/coder) deployment running. | ||||||
| Replace `https://coder.example.com` with your Coder deployment access URL. This also assumes | ||||||
| you have a template that has a parameter for a git repository URL (e.g. `git_repo_url`) that auto-clones | ||||||
| the repository or uses [envbuilder](https://coder.com/docs/v2/latest/templates/devcontainers) to build | ||||||
| the devcontainer. | ||||||
|
|
||||||
| 1. If you have a standalone app (you didn't clone this repo), then do | ||||||
|
|
||||||
| ```bash | ||||||
| yarn --cwd packages/app add @coder/backstage-plugin-coder | ||||||
| ``` | ||||||
|
|
||||||
| 1. Add the proxy key to your `app-config.yaml`: | ||||||
|
|
||||||
| ```yaml | ||||||
| proxy: | ||||||
| endpoints: | ||||||
| '/coder': | ||||||
| # Replace with your Coder deployment access URL and a trailing / | ||||||
| target: 'https://coder.example.com/' | ||||||
| changeOrigin: true | ||||||
| allowedMethods: ['GET'] | ||||||
| allowedHeaders: ['Authorization', 'Coder-Session-Token'] | ||||||
| headers: | ||||||
| X-Custom-Source: backstage | ||||||
| ``` | ||||||
|
|
||||||
| 1. Add the `CoderProvider` to the application: | ||||||
bpmct marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
|
||||||
| ```tsx | ||||||
| // In packages/app/src/App.tsx | ||||||
| import { | ||||||
| type CoderAppConfig, | ||||||
| CoderProvider, | ||||||
| } from '@coder/backstage-plugin-coder'; | ||||||
|
|
||||||
| const appConfig: CoderAppConfig = { | ||||||
| deployment: { | ||||||
| accessUrl: 'https://coder.example.com', | ||||||
| }, | ||||||
|
|
||||||
| // Set the default template (and parameters) for | ||||||
| // catalog items. This can be overridden in the | ||||||
| // catalog-info.yaml for specific items. | ||||||
| workspaces: { | ||||||
| templateName: 'devcontainers', | ||||||
| mode: 'manual', | ||||||
| // This parameter is used to filter Coder workspaces | ||||||
| // by a repo URL parameter. | ||||||
| repoUrlParamKeys: ['custom_repo', 'repo_url'], | ||||||
|
There was a problem hiding this comment. Think it might be help to make it more clear that this is specifically for specifying multiple parameters for the repo URL, if a company somehow has multiple teams using different key names There's a section in the API Reference that mentions the general order of operations that the logic uses to process these parameter names. Might be worth linking to it once the API docs are good to go There was a problem hiding this comment. I'm not sure how a single template would be supported, but multiple parameters for repo, unless I'm missing something. I think we leave it in the API reference for now. |
||||||
| params: { | ||||||
| repo: 'custom', | ||||||
| region: 'eu-helsinki', | ||||||
| }, | ||||||
| }, | ||||||
| }; | ||||||
|
|
||||||
| // ... | ||||||
|
|
||||||
| export default app.createRoot( | ||||||
| <CoderProvider appConfig={appConfig}> | ||||||
| <AlertDisplay /> | ||||||
| <OAuthRequestDialog /> | ||||||
| <AppRouter> | ||||||
| <Root>{routes}</Root> | ||||||
| </AppRouter> | ||||||
| </CoderProvider>, | ||||||
| ); | ||||||
| ``` | ||||||
|
|
||||||
| 1. Add the `WorkspacesList` card to the entity page in your app: | ||||||
|
There was a problem hiding this comment.
Suggested change
Do you also think that it's worth shouting out that the individual pieces will be available as imports, too, for people who want more customization options, or can that stay more of a footnote in the API docs? There was a problem hiding this comment. Yeah, that would be excellent. Will we have an example of that in the API docs? Left a comment for now. |
||||||
|
|
||||||
| ```tsx | ||||||
| // In packages/app/src/components/catalog/EntityPage.tsx | ||||||
| import { CoderWorkspacesCard } from '@coder/backstage-plugin-coder'; | ||||||
|
|
||||||
| // ... | ||||||
|
|
||||||
| <Grid item md={6} xs={12}> | ||||||
| <CoderWorkspacesCard readEntityData /> | ||||||
| </Grid>; | ||||||
| ``` | ||||||
|
|
||||||
| See [the plugin documentation](./docs) for full configuration options and API reference. | ||||||
|
|
||||||
| ### API Access | ||||||
|
|
||||||
| The plugin provides a `CoderApi` instance for accessing the Coder API. This can be used in custom plugins and integrations. Here is an example component that lists all templates: | ||||||
|
|
||||||
| ```tsx | ||||||
| import { useCoder } from '@coder/backstage-plugin-coder'; | ||||||
|
|
||||||
| // TODO. I believe Michael said this is possible today? | ||||||
| // This can be a very basic component that requires auth | ||||||
| // and lists all templates in a basic unstyled list | ||||||
| // with a refresh button | ||||||
|
Comment on lines
+116
to
+119
There was a problem hiding this comment. Yeah, this depends on your definition of "possible today". With the current proxy settings, it is possible to hit any arbitrary endpoint, though there's zero type-safety/type-hints or good ergonomics around it. There's also not a great way to bring the Coder session token from the other UI components into any arbitrary fetch call Again, though, these changes are perfectly doable in time for launch – they're just not ready quite yet There was a problem hiding this comment. Gotcha. Commented out fo rnow |
||||||
| ``` | ||||||
|
|
||||||
| See to the [Coder REST API Reference](https://coder.com/docs/v2/latest/api) for more details | ||||||
|
|
||||||
| ## Roadmap | ||||||
|
|
||||||
| This plugin is in active development. The following features are planned: | ||||||
|
|
||||||
| - [ ] Add support for only rendering component if `catalog-info.yaml` indicates the item is compatible with Coder | ||||||
|
There was a problem hiding this comment. I don't think this would be too hard – my gut feeling is that we would basically export a custom hook (something like I think that'll be the best option for giving devs the most control, since there's so much freedom as far as where the component can be placed, and blindly hiding an element could cause layout jank in our user's webpages. Though on top of this, we could also add a property to the component that says whether to render at all |
||||||
| - [ ] OAuth support (vs. token auth) for linking Coder accounts | ||||||
| - [ ] "Open in Coder" button/card component for catalog items | ||||||
| - [ ] Example creating workspaces with Backstage Scaffolder | ||||||
| - [ ] Example dedicated "Coder" page in Backstage | ||||||
bpmct marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
|
||||||
| ## Contributing | ||||||
|
|
||||||
| This plugin is part of the Backstage community. We welcome contributions! | ||||||
Uh oh!
There was an error while loading. Please reload this page.