|
1 | | -# coder-backstage |
2 | | - |
3 | | -A basic plugin that adds the "Open in Coder" button to catalog items in backstage based on |
4 | | -the catalog spec. |
5 | | - |
6 | | -| Catalog item without Coder | Catalog item with Coder | |
7 | | -| ---------------------------------------------------------------- | ---------------------------------------------------------- | |
8 | | -|  |  | |
9 | | - |
10 | | -This is a very basic MVP, but demonstrates the power of a Coder+Backstage integration. It allows Backstage users to quickly develop a service inside a CDE. |
11 | | - |
12 | | -## How it works |
13 | | - |
14 | | -All backstage catalog items are git repos with a [catalog-info.yaml](https://github.com/bcdr-demos/python-project/blob/main/catalog-info.yaml) file. To add Coder compatibility to a given template, we need to add a `coder` section to the catalog-info.yaml file. |
15 | | - |
16 | | -Here's an example: |
17 | | - |
18 | | -```yaml |
19 | | -apiVersion: backstage.io/v1alpha1 |
20 | | -kind: Component |
21 | | -metadata: |
22 | | - name: python-project |
23 | | -spec: |
24 | | - type: other |
25 | | - lifecycle: unknown |
26 | | - owner: pm |
27 | | - coder: |
28 | | - template: 'devcontainers' |
29 | | - createMode: 'auto' |
30 | | - params: |
31 | | - repo: 'custom' |
32 | | - repo_url: 'https://github.com/bcdr-demos/python-project' |
33 | | - region: 'us-pittsburgh' |
34 | | -``` |
| 1 | +# @coder/backstage-plugin-coder |
| 2 | + |
| 3 | +Create and manage [Coder workspaces](https://coder.com/docs/v2/latest) from Backstage. |
| 4 | + |
| 5 | +<!-- TOOD: Add Loom --> |
| 6 | + |
| 7 | +## Screenshots |
| 8 | + |
| 9 | + |
35 | 10 |
|
36 | | -## Adding the component |
| 11 | + |
37 | 12 |
|
38 | | -Since the Backstage UI is "DIY," you'll need to modify `EntityPage.tsx` in your Backstage deployment to import the components from this plugin. |
| 13 | +## Features |
39 | 14 |
|
40 | | -There are several ways to use the integration: |
| 15 | +- Users link their Coder accounts with Backstage via tokens |
| 16 | +- Associate Coder workspaces with catalog items in Backstage |
| 17 | +- Workspace list component for viewing and managing workspaces |
| 18 | +<!-- - Full Coder API access for custom plugins & integrations --> |
41 | 19 |
|
42 | | -### Example Card |
| 20 | +## Setup |
43 | 21 |
|
44 | | -The easiest way to consume this integration is by importing the `ExampleContributingCard` component |
| 22 | +This assumes you already have a [Coder](https://github.com/coder/coder) deployment running. |
| 23 | +Replace `https://coder.example.com` with your Coder deployment access URL. This also assumes |
| 24 | +you have a template that has a parameter for a git repository URL (e.g. `git_repo_url`) that auto-clones |
| 25 | +the repository or uses [envbuilder](https://coder.com/docs/v2/latest/templates/devcontainers) to build |
| 26 | +the devcontainer. |
45 | 27 |
|
46 | | -```tsx |
47 | | -// EntityPage.tsx |
48 | | -import { ExampleContributingCard } from '@internal/plugin-coder'; |
49 | | -
|
50 | | -// ... |
51 | | -const overviewContent = ( |
52 | | - <Grid container spacing={3} alignItems="stretch"> |
53 | | - {/* ... */} |
54 | | - <Grid item md={6} xs={12}> |
55 | | - <ExampleContributingCard coderAccessUrl="https://coder.example.com" /> |
56 | | - </Grid> |
57 | | - {/* ... */} |
58 | | - </Grid> |
59 | | -); |
60 | | -``` |
| 28 | +1. If you have a standalone Backstage app (you didn't clone this repo), then do |
| 29 | + |
| 30 | + ```bash |
| 31 | + yarn --cwd packages/app add @coder/backstage-plugin-coder |
| 32 | + ``` |
| 33 | + |
| 34 | +1. Add the proxy key to your `app-config.yaml`: |
| 35 | + |
| 36 | + ```yaml |
| 37 | + proxy: |
| 38 | + endpoints: |
| 39 | + '/coder': |
| 40 | + # Replace with your Coder deployment access URL and a trailing / |
| 41 | + target: 'https://coder.example.com/' |
| 42 | + changeOrigin: true |
| 43 | + allowedMethods: ['GET'] |
| 44 | + allowedHeaders: ['Authorization', 'Coder-Session-Token'] |
| 45 | + headers: |
| 46 | + X-Custom-Source: backstage |
| 47 | + ``` |
| 48 | +
|
| 49 | +1. Add the `CoderProvider` to the application: |
| 50 | + |
| 51 | + ```tsx |
| 52 | + // In packages/app/src/App.tsx |
| 53 | + import { |
| 54 | + type CoderAppConfig, |
| 55 | + CoderProvider, |
| 56 | + } from '@coder/backstage-plugin-coder'; |
61 | 57 |
|
62 | | -### Button |
| 58 | + const appConfig: CoderAppConfig = { |
| 59 | + deployment: { |
| 60 | + accessUrl: 'https://coder.example.com', |
| 61 | + }, |
63 | 62 |
|
64 | | -You can also just import the `OpenInCoderButton` component and use it in your own component. |
| 63 | + // Set the default template (and parameters) for |
| 64 | + // catalog items. This can be overridden in the |
| 65 | + // catalog-info.yaml for specific items. |
| 66 | + workspaces: { |
| 67 | + templateName: 'devcontainers', |
| 68 | + mode: 'manual', |
| 69 | + // This parameter is used to filter Coder workspaces |
| 70 | + // by a repo URL parameter. |
| 71 | + repoUrlParamKeys: ['custom_repo', 'repo_url'], |
| 72 | + params: { |
| 73 | + repo: 'custom', |
| 74 | + region: 'eu-helsinki', |
| 75 | + }, |
| 76 | + }, |
| 77 | + }; |
65 | 78 |
|
66 | | -### URL |
| 79 | + // ... |
67 | 80 |
|
68 | | -For the most control, you can use the `useOpenInCoderLink` to get the Coder URL for a given catalog item. |
| 81 | + export default app.createRoot( |
| 82 | + <CoderProvider appConfig={appConfig}> |
| 83 | + <AlertDisplay /> |
| 84 | + <OAuthRequestDialog /> |
| 85 | + <AppRouter> |
| 86 | + <Root>{routes}</Root> |
| 87 | + </AppRouter> |
| 88 | + </CoderProvider>, |
| 89 | + ); |
| 90 | + ``` |
69 | 91 |
|
70 | | -```ts |
71 | | -// MyCustomComponent.tsx |
72 | | -import { useOpenInCoderLink } from '@internal/plugin-coder'; |
| 92 | + <!-- > Note: You can also wrap a single page or component with `CoderProvider` if you only need Coder in a specific part of your app. See our [API reference](#TODO) for more details. --> |
73 | 93 |
|
74 | | -export const MyCustomComponent = () => { |
75 | | - const coderLink = useOpenInCoderLink(catalogItem); |
76 | | - // some basic component that has error handling if coderLink is null |
77 | | - if (coderLink) return <a href={coderLink}>Open in Coder</a>; |
78 | | - return <p>Not configured for Coder</p>; |
79 | | -}; |
| 94 | +1. Add the `CoderWorkspacesCard` card to the entity page in your app: |
| 95 | + |
| 96 | + ```tsx |
| 97 | + // In packages/app/src/components/catalog/EntityPage.tsx |
| 98 | + import { CoderWorkspacesCard } from '@coder/backstage-plugin-coder'; |
| 99 | +
|
| 100 | + // ... |
| 101 | +
|
| 102 | + <Grid item md={6} xs={12}> |
| 103 | + <CoderWorkspacesCard readEntityData /> |
| 104 | + </Grid>; |
| 105 | + ``` |
| 106 | + |
| 107 | +<!-- Individual components of the card can also be imported. See [the plugin documentation](./docs) for full configuration options and API reference. --> |
| 108 | + |
| 109 | +<!-- ### API Access |
| 110 | + |
| 111 | +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: |
| 112 | + |
| 113 | +```tsx |
| 114 | +import { useCoder } from '@coder/backstage-plugin-coder'; |
| 115 | +
|
| 116 | +// TODO. I believe Michael said this is possible today? |
| 117 | +// This can be a very basic component that requires auth |
| 118 | +// and lists all templates in a basic unstyled list |
| 119 | +// with a refresh button |
80 | 120 | ``` |
81 | 121 |
|
82 | | -## Taking this further |
| 122 | +See to the [Coder REST API Reference](https://coder.com/docs/v2/latest/api) for more details --> |
83 | 123 |
|
84 | | -This is only the beginning. We can extend this integration further: |
| 124 | +## Roadmap |
85 | 125 |
|
86 | | -- [ ] Display Coder-compatible templates in the catalog |
87 | | -- [ ] Developing a neutral Backstage plugin to detect `devcontainer.json` in repos and add a more advanced "contributing" card that links to VS Code Remote, Codespaces, and Coder |
88 | | -- [ ] Allow developers to see their existing Coder workspaces and relate workspaces more directly to catalog items |
89 | | -- [ ] Allow developers to create new workspaces from the catalog item page or a dedicated sidebar page |
90 | | -- [ ] Build an IDE extension to allow people to see catalog items and start a new project, and open their CDE, without leaving their editor! |
| 126 | +This plugin is in active development. The following features are planned: |
91 | 127 |
|
92 | | -More ideas welcome! |
| 128 | +- [ ] Add support for only rendering component if `catalog-info.yaml` indicates the item is compatible with Coder |
| 129 | +- [ ] OAuth support (vs. token auth) for linking Coder accounts |
| 130 | +- [ ] "Open in Coder" button/card component for catalog items |
| 131 | +- [ ] Example creating workspaces with Backstage Scaffolder |
| 132 | +- [ ] Example dedicated "Coder" page in Backstage |
93 | 133 |
|
94 | 134 | ## Contributing |
95 | 135 |
|
96 | | -Your plugin has been added to the example app in this repository, meaning you'll be able to access it by running `yarn start` in the root directory, and then navigating to [/coder](http://localhost:3000/coder). |
97 | | - |
98 | | -You can also serve the plugin in isolation by running `yarn start` in the plugin directory. |
99 | | -This method of serving the plugin provides quicker iteration speed and a faster startup and hot reloads. |
100 | | -It is only meant for local development, and the setup for it can be found inside the [/dev](./dev) directory. |
| 136 | +This plugin is part of the Backstage community. We welcome contributions! |
0 commit comments