Merge branch 'master' into mobile-sidebar
Signed-off-by: Philipp Hugenroth <philipph@spotify.com>
This commit is contained in:
Philipp Hugenroth
@@ -54,3 +54,10 @@ const darkTheme = {
|
||||
),
|
||||
};
|
||||
```
|
||||
|
||||
Note that the existing `AppTheme` type still requires the `theme` property to be
|
||||
set since it's the type that's consumed in the `AppThemeApi`, and it would be a
|
||||
breaking change to make `theme` optional. This means that if you currently
|
||||
construct the themes that you pass on to `createApp` using `AppTheme` as an
|
||||
intermediate type, you will need to work around this in some way, for example by
|
||||
passing the themes to `createApp` more directly.
|
||||
|
||||
@@ -291,7 +291,7 @@ The figure below shows the relationship between
|
||||
<span style="color: #b85450">fooApiRef</span>.
|
||||
|
||||
<div style="text-align:center">
|
||||
<img src="../assets/utility-apis-fig1.svg" alt="Figure showing the relationship between utility APIs, the apps that provide them, and the plugins that consume them">
|
||||
<img src="../assets/utility-apis-fig1.svg" alt="Figure showing the relationship between utility APIs, the apps that provide them, and the plugins that consume them" />
|
||||
</div>
|
||||
|
||||
The current method for connecting Utility API providers and consumers is via the
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
id: adrs-adr012
|
||||
title: ADR000: Use Luxon.toLocaleString and date/time presets
|
||||
title: ADR012: Use Luxon.toLocaleString and date/time presets
|
||||
description: Architecture Decision Record (ADR) for using Luxon's toLocaleString method and date/time presets for displaying dates and times
|
||||
---
|
||||
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 1.1 MiB |
@@ -229,7 +229,7 @@ name.
|
||||
|
||||
### Test the new provider
|
||||
|
||||
You can `curl -i localhost:7000/api/auth/providerA/start` and which should
|
||||
You can `curl -i localhost:7007/api/auth/providerA/start` and which should
|
||||
provide a `302` redirect with a `Location` header. Paste the url from that
|
||||
header into a web browser and you should be able to trigger the authorization
|
||||
flow.
|
||||
|
||||
@@ -28,7 +28,7 @@ Name your integration and click on the `Create` button.
|
||||
|
||||
Settings for local development:
|
||||
|
||||
- Callback URL: `http://localhost:7000/api/auth/atlassian`
|
||||
- Callback URL: `http://localhost:7007/api/auth/atlassian`
|
||||
- Use rotating refresh tokens
|
||||
- For permissions, you **must** enable `View user profile` for the currently
|
||||
logged-in user, under `User identity API`
|
||||
|
||||
@@ -17,7 +17,7 @@ provider that can authenticate users using OAuth.
|
||||
- Application type: Single Page Web Application
|
||||
4. Click on the Settings tab
|
||||
5. Add under `Application URIs` > `Allowed Callback URLs`:
|
||||
`http://localhost:7000/api/auth/auth0/handler/frame`
|
||||
`http://localhost:7007/api/auth/auth0/handler/frame`
|
||||
6. Click `Save Changes`
|
||||
|
||||
## Configuration
|
||||
|
||||
@@ -20,7 +20,7 @@ Click Add Consumer.
|
||||
Settings for local development:
|
||||
|
||||
- Application name: Backstage (or your custom app name)
|
||||
- Callback URL: `http://localhost:7000/api/auth/bitbucket`
|
||||
- Callback URL: `http://localhost:7007/api/auth/bitbucket`
|
||||
- Other are optional
|
||||
- (IMPORTANT) **Permissions: Account - Read, Workspace membership - Read**
|
||||
|
||||
|
||||
@@ -24,7 +24,7 @@ Settings for local development:
|
||||
|
||||
- Application name: Backstage (or your custom app name)
|
||||
- Homepage URL: `http://localhost:3000`
|
||||
- Authorization callback URL: `http://localhost:7000/api/auth/github`
|
||||
- Authorization callback URL: `http://localhost:7007/api/auth/github`
|
||||
|
||||
## Configuration
|
||||
|
||||
|
||||
@@ -17,7 +17,7 @@ should point to your Backstage backend auth handler.
|
||||
Settings for local development:
|
||||
|
||||
- Name: Backstage (or your custom app name)
|
||||
- Redirect URI: `http://localhost:7000/api/auth/gitlab/handler/frame`
|
||||
- Redirect URI: `http://localhost:7007/api/auth/gitlab/handler/frame`
|
||||
- Scopes: read_user
|
||||
|
||||
## Configuration
|
||||
|
||||
@@ -26,7 +26,7 @@ To support Google authentication, you must create OAuth credentials:
|
||||
- `Name`: Backstage (or your custom app name)
|
||||
- `Authorized JavaScript origins`: http://localhost:3000
|
||||
- `Authorized Redirect URIs`:
|
||||
http://localhost:7000/api/auth/google/handler/frame
|
||||
http://localhost:7007/api/auth/google/handler/frame
|
||||
7. Click Create
|
||||
|
||||
## Configuration
|
||||
|
||||
@@ -16,8 +16,10 @@ Backstage identity information in your app or plugins.
|
||||
|
||||
Backstage comes with many common authentication providers in the core library:
|
||||
|
||||
- [Atlassian](atlassian/provider.md)
|
||||
- [Auth0](auth0/provider.md)
|
||||
- [Azure](microsoft/provider.md)
|
||||
- [Bitbucket](bitbucket/provider.md)
|
||||
- [GitHub](github/provider.md)
|
||||
- [GitLab](gitlab/provider.md)
|
||||
- [Google](google/provider.md)
|
||||
|
||||
@@ -21,7 +21,7 @@ To support Azure authentication, you must create an App Registration:
|
||||
4. Register an application
|
||||
- Name: Backstage (or your custom app name)
|
||||
- Redirect URI: Web >
|
||||
`http://localhost:7000/api/auth/microsoft/handler/frame`
|
||||
`http://localhost:7007/api/auth/microsoft/handler/frame`
|
||||
5. Navigate to **Certificates & secrets > New client secret** to create a secret
|
||||
|
||||
## Configuration
|
||||
|
||||
@@ -22,8 +22,8 @@ To add Okta authentication, you must create an Application from Okta:
|
||||
- `App integration name`: `Backstage` (or your custom app name)
|
||||
- `Grant type`: `Authorization Code` & `Refresh Token`
|
||||
- `Sign-in redirect URIs`:
|
||||
`http://localhost:7000/api/auth/okta/handler/frame`
|
||||
- `Sign-out redirect URIs`: `http://localhost:7000`
|
||||
`http://localhost:7007/api/auth/okta/handler/frame`
|
||||
- `Sign-out redirect URIs`: `http://localhost:7007`
|
||||
- `Controlled access`: (select as appropriate)
|
||||
- Click Save
|
||||
|
||||
|
||||
@@ -18,7 +18,7 @@ To support OneLogin authentication, you must create an Application:
|
||||
3. Click Save
|
||||
4. Go to the Configuration tab for the Application and set:
|
||||
- `Login Url`: `http://localhost:3000`
|
||||
- `Redirect URIs`: `http://localhost:7000/api/auth/onelogin/handler/frame`
|
||||
- `Redirect URIs`: `http://localhost:7007/api/auth/onelogin/handler/frame`
|
||||
5. Click Save
|
||||
6. Go to the SSO tab for the Application and set:
|
||||
- `Token Endpoint` > `Authentication Method`: `POST`
|
||||
|
||||
@@ -16,8 +16,8 @@ app:
|
||||
baseUrl: http://localhost:3000
|
||||
|
||||
backend:
|
||||
listen: 0.0.0.0:7000
|
||||
baseUrl: http://localhost:7000
|
||||
listen: 0.0.0.0:7007
|
||||
baseUrl: http://localhost:7007
|
||||
|
||||
organization:
|
||||
name: CNCF
|
||||
|
||||
@@ -7,9 +7,9 @@ description: How to build a Backstage Docker image for deployment
|
||||
|
||||
This section describes how to build a Backstage App into a deployable Docker
|
||||
image. It is split into three sections, first covering the host build approach,
|
||||
which is recommended due its speed and more efficient and often simpler caching.
|
||||
The second section covers a full multi-stage Docker build, and the last section
|
||||
covers how to deploy the frontend and backend as separate images.
|
||||
which is recommended due to its speed and more efficient and often simpler
|
||||
caching. The second section covers a full multi-stage Docker build, and the last
|
||||
section covers how to deploy the frontend and backend as separate images.
|
||||
|
||||
Something that goes for all of these docker deployment strategies is that they
|
||||
are stateless, so for a production deployment you will want to set up and
|
||||
@@ -105,11 +105,11 @@ docker image build . -f packages/backend/Dockerfile --tag backstage
|
||||
To try out the image locally you can run the following:
|
||||
|
||||
```sh
|
||||
docker run -it -p 7000:7000 backstage
|
||||
docker run -it -p 7007:7007 backstage
|
||||
```
|
||||
|
||||
You should then start to get logs in your terminal, and then you can open your
|
||||
browser at `http://localhost:7000`
|
||||
browser at `http://localhost:7007`
|
||||
|
||||
## Multi-stage Build
|
||||
|
||||
@@ -208,11 +208,11 @@ docker image build -t backstage .
|
||||
To try out the image locally you can run the following:
|
||||
|
||||
```sh
|
||||
docker run -it -p 7000:7000 backstage
|
||||
docker run -it -p 7007:7007 backstage
|
||||
```
|
||||
|
||||
You should then start to get logs in your terminal, and then you can open your
|
||||
browser at `http://localhost:7000`
|
||||
browser at `http://localhost:7007`
|
||||
|
||||
## Separate Frontend
|
||||
|
||||
|
||||
@@ -351,7 +351,7 @@ spec:
|
||||
imagePullPolicy: IfNotPresent
|
||||
ports:
|
||||
- name: http
|
||||
containerPort: 7000
|
||||
containerPort: 7007
|
||||
envFrom:
|
||||
- secretRef:
|
||||
name: postgres-secrets
|
||||
@@ -361,11 +361,11 @@ spec:
|
||||
# https://backstage.io/docs/plugins/observability#health-checks
|
||||
# readinessProbe:
|
||||
# httpGet:
|
||||
# port: 7000
|
||||
# port: 7007
|
||||
# path: /healthcheck
|
||||
# livenessProbe:
|
||||
# httpGet:
|
||||
# port: 7000
|
||||
# port: 7007
|
||||
# path: /healthcheck
|
||||
```
|
||||
|
||||
@@ -449,7 +449,7 @@ spec:
|
||||
```
|
||||
|
||||
The `selector` here is telling the Service which pods to target, and the port
|
||||
mapping translates normal HTTP port 80 to the backend http port (7000) on the
|
||||
mapping translates normal HTTP port 80 to the backend http port (7007) on the
|
||||
pod.
|
||||
|
||||
Apply this Service to the Kubernetes cluster:
|
||||
@@ -464,10 +464,10 @@ reveal**_, you can forward a local port to the service:
|
||||
|
||||
```shell
|
||||
$ sudo kubectl port-forward --namespace=backstage svc/backstage 80:80
|
||||
Forwarding from 127.0.0.1:80 -> 7000
|
||||
Forwarding from 127.0.0.1:80 -> 7007
|
||||
```
|
||||
|
||||
This shows port 7000 since `port-forward` doesn't _really_ support services, so
|
||||
This shows port 7007 since `port-forward` doesn't _really_ support services, so
|
||||
it cheats by looking up the first pod for a service and connecting to the mapped
|
||||
pod port.
|
||||
|
||||
@@ -486,7 +486,7 @@ organization:
|
||||
backend:
|
||||
baseUrl: http://localhost
|
||||
listen:
|
||||
port: 7000
|
||||
port: 7007
|
||||
cors:
|
||||
origin: http://localhost
|
||||
```
|
||||
|
||||
@@ -26,6 +26,7 @@ kubernetes:
|
||||
name: minikube
|
||||
authProvider: 'serviceAccount'
|
||||
skipTLSVerify: false
|
||||
skipMetricsLookup: true
|
||||
serviceAccountToken: ${K8S_MINIKUBE_TOKEN}
|
||||
dashboardUrl: http://127.0.0.1:64713 # url copied from running the command: minikube service kubernetes-dashboard -n kubernetes-dashboard
|
||||
dashboardApp: standard
|
||||
@@ -37,6 +38,7 @@ kubernetes:
|
||||
projectId: 'gke-clusters'
|
||||
region: 'europe-west1'
|
||||
skipTLSVerify: true
|
||||
skipMetricsLookup: true
|
||||
```
|
||||
|
||||
### `serviceLocatorMethod`
|
||||
@@ -86,8 +88,13 @@ cluster. Valid values are:
|
||||
|
||||
##### `clusters.\*.skipTLSVerify`
|
||||
|
||||
This determines whether or not the Kubernetes client verifies the TLS
|
||||
certificate presented by the API server. Defaults to `false`.
|
||||
This determines whether the Kubernetes client verifies the TLS certificate
|
||||
presented by the API server. Defaults to `false`.
|
||||
|
||||
##### `clusters.\*.skipMetricsLookup`
|
||||
|
||||
This determines whether the Kubernetes client looks up resource metrics
|
||||
CPU/Memory for pods returned by the API server. Defaults to `false`.
|
||||
|
||||
##### `clusters.\*.serviceAccountToken` (optional)
|
||||
|
||||
@@ -188,8 +195,13 @@ regions.
|
||||
|
||||
##### `skipTLSVerify`
|
||||
|
||||
This determines whether or not the Kubernetes client verifies the TLS
|
||||
certificate presented by the API server. Defaults to `false`.
|
||||
This determines whether the Kubernetes client verifies the TLS certificate
|
||||
presented by the API server. Defaults to `false`.
|
||||
|
||||
##### `skipMetricsLookup`
|
||||
|
||||
This determines whether the Kubernetes client looks up resource metrics
|
||||
CPU/Memory for pods returned by the API server. Defaults to `false`.
|
||||
|
||||
### `customResources` (optional)
|
||||
|
||||
@@ -219,6 +231,26 @@ The custom resource's apiVersion.
|
||||
|
||||
The plural representing the custom resource.
|
||||
|
||||
### `apiVersionOverrides` (optional)
|
||||
|
||||
Overrides for the API versions used to make requests for the corresponding
|
||||
objects. If using a legacy Kubernetes version, you may use this config to
|
||||
override the default API versions to ones that are supported by your cluster.
|
||||
|
||||
Example:
|
||||
|
||||
```yaml
|
||||
---
|
||||
kubernetes:
|
||||
apiVersionOverrides:
|
||||
cronjobs: 'v1beta1'
|
||||
```
|
||||
|
||||
For more information on which API versions are supported by your cluster, please
|
||||
view the Kubernetes API docs for your Kubernetes version (e.g.
|
||||
[API Groups for v1.22](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#-strong-api-groups-strong-)
|
||||
)
|
||||
|
||||
### Role Based Access Control
|
||||
|
||||
The current RBAC permissions required are read-only cluster wide, for the
|
||||
|
||||
@@ -114,13 +114,15 @@ const routes = (
|
||||
In `Root.tsx`, add the `SidebarSearchModal` component:
|
||||
|
||||
```bash
|
||||
import { SidebarSearchModal } from '@backstage/plugin-search';
|
||||
import { SidebarSearchModal, SearchContextProvider } from '@backstage/plugin-search';
|
||||
|
||||
export const Root = ({ children }: PropsWithChildren<{}>) => (
|
||||
<SidebarPage>
|
||||
<Sidebar>
|
||||
<SidebarLogo />
|
||||
<SidebarSearchModal />
|
||||
<SearchContextProvider>
|
||||
<SidebarSearchModal />
|
||||
</SearchContextProvider>
|
||||
<SidebarDivider />
|
||||
...
|
||||
```
|
||||
@@ -154,13 +156,17 @@ import { DefaultCatalogCollator } from '@backstage/plugin-catalog-backend';
|
||||
export default async function createPlugin({
|
||||
logger,
|
||||
discovery,
|
||||
tokenManager,
|
||||
}: PluginEnvironment) {
|
||||
const searchEngine = new LunrSearchEngine({ logger });
|
||||
const indexBuilder = new IndexBuilder({ logger, searchEngine });
|
||||
|
||||
indexBuilder.addCollator({
|
||||
defaultRefreshIntervalSeconds: 600,
|
||||
collator: new DefaultCatalogCollator({ discovery }),
|
||||
collator: new DefaultCatalogCollator({
|
||||
discovery,
|
||||
tokenManager,
|
||||
}),
|
||||
});
|
||||
|
||||
const { scheduler } = await indexBuilder.build();
|
||||
@@ -285,7 +291,10 @@ const indexBuilder = new IndexBuilder({ logger, searchEngine });
|
||||
|
||||
indexBuilder.addCollator({
|
||||
defaultRefreshIntervalSeconds: 600,
|
||||
collator: new DefaultCatalogCollator({ discovery }),
|
||||
collator: new DefaultCatalogCollator({
|
||||
discovery,
|
||||
tokenManager,
|
||||
}),
|
||||
});
|
||||
|
||||
indexBuilder.addCollator({
|
||||
@@ -303,6 +312,9 @@ its `defaultRefreshIntervalSeconds` value, like this:
|
||||
```typescript {3}
|
||||
indexBuilder.addCollator({
|
||||
defaultRefreshIntervalSeconds: 600,
|
||||
collator: new DefaultCatalogCollator({ discovery }),
|
||||
collator: new DefaultCatalogCollator({
|
||||
discovery,
|
||||
tokenManager,
|
||||
}),
|
||||
});
|
||||
```
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
id: how-to-guides
|
||||
title: Search "HOW TO" guides
|
||||
sidebar_label: "HOW TO" guides
|
||||
description: Search "HOW TO" guides
|
||||
description: Search "HOW TO" guides
|
||||
---
|
||||
|
||||
## How to implement your own Search API
|
||||
@@ -74,6 +74,7 @@ indexBuilder.addCollator({
|
||||
collator: DefaultTechDocsCollator.fromConfig(config, {
|
||||
discovery,
|
||||
logger,
|
||||
tokenManager,
|
||||
}),
|
||||
});
|
||||
```
|
||||
|
||||
@@ -4,9 +4,9 @@ title: Search Engines
|
||||
description: Choosing and configuring your search engine for Backstage
|
||||
---
|
||||
|
||||
Backstage supports 2 search engines by default, an in-memory engine called Lunr
|
||||
and ElasticSearch. You can configure your own search engines by implementing the
|
||||
provided interface as mentioned in the
|
||||
Backstage supports 3 search engines by default, an in-memory engine called Lunr,
|
||||
ElasticSearch and Postgres. You can configure your own search engines by
|
||||
implementing the provided interface as mentioned in the
|
||||
[search backend documentation.](./getting-started.md#Backend)
|
||||
|
||||
Provided search engine implementations have their own way of constructing
|
||||
|
||||
@@ -53,3 +53,30 @@ You can do so by including the following lines in the last step of your
|
||||
RUN apt-get update && apt-get install -y python3 python3-pip
|
||||
RUN pip3 install cookiecutter
|
||||
```
|
||||
|
||||
### Customizing the ScaffolderPage with Grouping and Filtering
|
||||
|
||||
Once you have more than a few software templates you may want to customize your
|
||||
`ScaffolderPage` by grouping and surfacing certain templates together. You can
|
||||
accomplish this by creating `groups` and passing them to your `ScaffolderPage`
|
||||
like below
|
||||
|
||||
```
|
||||
<ScaffolderPage
|
||||
groups={[
|
||||
{
|
||||
title: "Recommended",
|
||||
filter: entity =>
|
||||
entity?.metadata?.tags?.includes('recommended') ?? false,
|
||||
},
|
||||
]}
|
||||
/>
|
||||
```
|
||||
|
||||
This code will group all templates with the 'recommended' tag together at the
|
||||
top of the page above any other templates not filtered by this group or others.
|
||||
|
||||
You can also further customize groups by passing in a `titleComponent` instead
|
||||
of a `title` which will be a component to use as the header instead of just the
|
||||
default `ContentHeader` with the `title` set as it's value.
|
||||
|
||||
|
||||
@@ -12,7 +12,7 @@ code, template in some variables, and then publish the template to some
|
||||
locations like GitHub or GitLab.
|
||||
|
||||
<video width="100%" height="100%" controls>
|
||||
<source src="https://backstage.io/blog/assets/2020-08-05/feature.mp4" type="video/mp4">
|
||||
<source src="https://backstage.io/blog/assets/2020-08-05/feature.mp4" type="video/mp4" />
|
||||
</video>
|
||||
|
||||
### Getting Started
|
||||
|
||||
@@ -8,6 +8,10 @@ If you're wanting to extend the functionality of the Scaffolder, you can do so
|
||||
by writing custom actions which can be used along side our
|
||||
[built-in actions](./builtin-actions.md).
|
||||
|
||||
> Note: When adding custom actions, the actions array will **replace the
|
||||
> built-in actions too**. To ensure you can continue to include he builtin
|
||||
> actions, see below to include them during registration of your action.
|
||||
|
||||
### Writing your Custom Action
|
||||
|
||||
Your custom action can live where you choose, but simplest is to include it
|
||||
@@ -91,6 +95,8 @@ argument. It looks like the following:
|
||||
- `createTemporaryDirectory` a function to call to give you a temporary
|
||||
directory somewhere on the runner so you can store some files there rather
|
||||
than polluting the `workspacePath`
|
||||
- `ctx.metadata` - an object containing a `name` field, indicating the template
|
||||
name. More metadata fields may be added later.
|
||||
|
||||
### Registering Custom Actions
|
||||
|
||||
@@ -113,22 +119,6 @@ return await createRouter({
|
||||
There's another property you can pass here, which is an array of `actions` which
|
||||
will set the available actions that the scaffolder has access to.
|
||||
|
||||
```ts
|
||||
const actions = [createNewFileAction()];
|
||||
return await createRouter({
|
||||
containerRunner,
|
||||
logger,
|
||||
config,
|
||||
database,
|
||||
catalogClient,
|
||||
reader,
|
||||
actions,
|
||||
});
|
||||
```
|
||||
|
||||
**NOTE** - the actions array will replace the built-in actions too, so if you
|
||||
want to have those as well as your new one, you'll need to do the following:
|
||||
|
||||
```ts
|
||||
import { createBuiltinActions } from '@backstage/plugin-scaffolder-backend';
|
||||
import { ScmIntegrations } from '@backstage/integration';
|
||||
@@ -144,7 +134,6 @@ const builtInActions = createBuiltinActions({
|
||||
});
|
||||
|
||||
const actions = [...builtInActions, createNewFileAction()];
|
||||
|
||||
return await createRouter({
|
||||
containerRunner,
|
||||
logger,
|
||||
|
||||
@@ -284,8 +284,8 @@ to publish to. And it can be any host that is listed in your `integrations`
|
||||
config in `app-config.yaml`.
|
||||
|
||||
The `RepoUrlPicker` is a custom field that we provide part of the
|
||||
`plugin-scaffolder`. It's currently not possible to create your own fields yet,
|
||||
but contributions are welcome! :)
|
||||
`plugin-scaffolder`. You can provide your own custom fields by
|
||||
[writing your own Custom Field Extensions](./writing-custom-field-extensions.md)
|
||||
|
||||
#### The Owner Picker
|
||||
|
||||
|
||||
@@ -138,11 +138,11 @@ techdocs:
|
||||
# (Optional and Legacy) TechDocs makes API calls to techdocs-backend using this URL. e.g. get docs of an entity, get metadata, etc.
|
||||
# You don't have to specify this anymore.
|
||||
|
||||
requestUrl: http://localhost:7000/api/techdocs
|
||||
requestUrl: http://localhost:7007/api/techdocs
|
||||
|
||||
# (Optional and Legacy) Just another route in techdocs-backend where TechDocs requests the static files from. This URL uses an HTTP middleware
|
||||
# to serve files from either a local directory or an External storage provider.
|
||||
# You don't have to specify this anymore.
|
||||
|
||||
storageUrl: http://localhost:7000/api/techdocs/static/docs
|
||||
storageUrl: http://localhost:7007/api/techdocs/static/docs
|
||||
```
|
||||
|
||||
@@ -43,7 +43,7 @@ the project root. Make sure you have run the above mentioned commands first.
|
||||
$ yarn dev
|
||||
```
|
||||
|
||||
This is going to start two things, the frontend (:3000) and the backend (:7000).
|
||||
This is going to start two things, the frontend (:3000) and the backend (:7007).
|
||||
|
||||
This should open a local instance of Backstage in your browser, otherwise open
|
||||
one of the URLs printed in the terminal.
|
||||
|
||||
@@ -36,7 +36,7 @@ This will create a new Backstage App inside the current folder. The name of the
|
||||
app-folder is the name that was provided when prompted.
|
||||
|
||||
<p align='center'>
|
||||
<img src='../assets/getting-started/create-app_output.png' width='600' alt='create app'>
|
||||
<img src='../assets/getting-started/create-app_output.png' width='600' alt='create app' />
|
||||
</p>
|
||||
|
||||
Inside that directory, it will generate all the files and folder structure
|
||||
|
||||
@@ -23,7 +23,7 @@ guide to do a repository-based installation.
|
||||
|
||||
- Access to a Linux-based operating system, such as Linux, MacOS or
|
||||
[Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/)
|
||||
- An account with elevated rights
|
||||
- An account with elevated rights to install the dependencies
|
||||
- `curl` or `wget` installed
|
||||
- Node.js Active LTS Release installed (currently v14) using one of these
|
||||
methods:
|
||||
@@ -36,15 +36,16 @@ guide to do a repository-based installation.
|
||||
- `yarn` [Installation](https://classic.yarnpkg.com/en/docs/install)
|
||||
- `docker` [installation](https://docs.docker.com/engine/install/)
|
||||
- `git` [installation](https://github.com/git-guides/install-git)
|
||||
- If the system is not directly accessible over your network, the following
|
||||
ports need to be opened: 3000, 7000
|
||||
- If the system is not directly accessible over your network the following ports
|
||||
need to be opened: 3000, 7007. This is quite uncommon, unless when you're
|
||||
installing in a container, VM or remote system.
|
||||
|
||||
### Create your Backstage App
|
||||
|
||||
To install the Backstage Standalone app, we make use of `npx`, a tool to run
|
||||
Node executables straight from the registry. Running the command below will
|
||||
install Backstage. The wizard will create a subdirectory inside your current
|
||||
working directory.
|
||||
Node executables straight from the registry. This tool is part of your Node.js
|
||||
installation. Running the command below will install Backstage. The wizard will
|
||||
create a subdirectory inside your current working directory.
|
||||
|
||||
```bash
|
||||
npx @backstage/create-app
|
||||
@@ -57,7 +58,7 @@ The wizard will ask you
|
||||
SQLite option.
|
||||
|
||||
<p align='center'>
|
||||
<img src='../assets/getting-started/wizard.png' alt='Screenshot of the wizard asking for a name for the app, and a selection menu for the database.'>
|
||||
<img src='../assets/getting-started/wizard.png' alt='Screenshot of the wizard asking for a name for the app, and a selection menu for the database.' />
|
||||
</p>
|
||||
|
||||
### Run the Backstage app
|
||||
@@ -72,18 +73,27 @@ yarn dev
|
||||
```
|
||||
|
||||
<p align='center'>
|
||||
<img src='../assets/getting-started/startup.png' alt='Screenshot of the command output, with the message web pack compiled successfully.'>
|
||||
<img src='../assets/getting-started/startup.png' alt='Screenshot of the command output, with the message web pack compiled successfully.'/>
|
||||
</p>
|
||||
|
||||
It might take a little while, but as soon as the message
|
||||
`[0] webpack compiled successfully` appears, you can open a browser and directly
|
||||
navigate to your freshly installed Backstage portal at `http://localhost:3000`.
|
||||
You can start exploring the demo immediately.
|
||||
You can start exploring the demo immediately. Please note that the in-memory
|
||||
database will be cleared when you restart the app, so you'll most likely want to
|
||||
carry on with the database steps.
|
||||
|
||||
<p align='center'>
|
||||
<img src='../assets/getting-started/portal.png' alt='Screenshot of the Backstage portal.'>
|
||||
<img src='../assets/getting-started/portal.png' alt='Screenshot of the Backstage portal.'/>
|
||||
</p>
|
||||
|
||||
The most common next steps are to move to a persistent database, configure
|
||||
authentication, and add a plugin:
|
||||
|
||||
- [Switching from SQLite to PostgresQL](https://backstage.io/docs/tutorials/switching-sqlite-postgres)
|
||||
- [Setting up Authentication](https://backstage.io/docs/auth/)
|
||||
- [Adding a plugin](https://backstage.io/docs/getting-started/configure-app-with-plugins)
|
||||
|
||||
Congratulations! That should be it. Let us know how it went:
|
||||
[on discord](https://discord.gg/EBHEGzX), file issues for any
|
||||
[feature](https://github.com/backstage/backstage/issues/new?labels=help+wanted&template=feature_template.md)
|
||||
@@ -93,10 +103,3 @@ or
|
||||
[bugs](https://github.com/backstage/backstage/issues/new?labels=bug&template=bug_template.md)
|
||||
you have, and feel free to
|
||||
[contribute](https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md)!
|
||||
|
||||
The most common next steps are to configure Backstage, add a plugin and moving
|
||||
to a more persistent database:
|
||||
|
||||
- [Setting up Authentication](https://backstage.io/docs/auth/)
|
||||
- [Switching from SQLite to PostgresQL](https://backstage.io/docs/tutorials/switching-sqlite-postgres)
|
||||
- [Adding a plugin](https://backstage.io/docs/getting-started/configure-app-with-plugins)
|
||||
|
||||
@@ -166,13 +166,9 @@ are separated out into their own folder, see further down.
|
||||
plugin and [techdocs-cli](https://github.com/backstage/techdocs-cli).
|
||||
|
||||
- [`test-utils/`](https://github.com/backstage/backstage/tree/master/packages/test-utils) -
|
||||
This package contains more general purpose testing facilities for testing a
|
||||
This package contains general purpose testing facilities for testing a
|
||||
Backstage App or its plugins.
|
||||
|
||||
- [`test-utils-core/`](https://github.com/backstage/backstage/tree/master/packages/test-utils-core) -
|
||||
This package contains specific testing facilities used when testing Backstage
|
||||
core internals.
|
||||
|
||||
- [`theme/`](https://github.com/backstage/backstage/tree/master/packages/theme) -
|
||||
Holds the Backstage Theme.
|
||||
|
||||
|
||||
@@ -70,7 +70,7 @@ cd packages/backend
|
||||
yarn start
|
||||
```
|
||||
|
||||
That starts up a backend instance on port 7000.
|
||||
That starts up a backend instance on port 7007.
|
||||
|
||||
In the other window, we will then launch the frontend. This command is run from
|
||||
the project root, not inside the backend directory.
|
||||
|
||||
@@ -0,0 +1,49 @@
|
||||
---
|
||||
id: discovery
|
||||
title: Azure DevOps Discovery
|
||||
sidebar_label: Discovery
|
||||
# prettier-ignore
|
||||
description: Automatically discovering catalog entities from repositories in an Azure DevOps organization
|
||||
---
|
||||
|
||||
The Azure DevOps integration has a special discovery processor for discovering
|
||||
catalog entities within an Azure DevOps. The processor will crawl the Azure
|
||||
DevOps organization and register entities matching the configured path. This can
|
||||
be useful as an alternative to static locations or manually adding things to the
|
||||
catalog.
|
||||
|
||||
To use the discovery processor, you'll need a GitHub integration
|
||||
[set up](locations.md) with a `AZURE_TOKEN`. Then you can add a location target
|
||||
to the catalog configuration:
|
||||
|
||||
```yaml
|
||||
catalog:
|
||||
locations:
|
||||
# Scan all repositories for a catalog-info.yaml in the root of the default branch
|
||||
- type: azure-discovery
|
||||
target: https://dev.azure.com/myorg/myproject
|
||||
# Or use a custom pattern for a subset of all repositories with default repository
|
||||
- type: azure-discovery
|
||||
target: https://dev.azure.com/myorg/myproject/_git/service-*
|
||||
# Or use a custom file format and location
|
||||
- type: azure-discovery
|
||||
target: https://dev.azure.com/myorg/myproject/_git/*?path=/src/*/catalog-info.yaml
|
||||
```
|
||||
|
||||
Note the `azure-discovery` type, as this is not a regular `url` processor.
|
||||
|
||||
When using a custom pattern, the target is composed of five parts:
|
||||
|
||||
- The base instance URL, `https://dev.azure.com` in this case
|
||||
- The organization name which is required, `myorg` in this case
|
||||
- The project name which is required, `myproject` in this case
|
||||
- The repository blob to scan, which accepts \* wildcard tokens and must be
|
||||
added after `_git/`. This can simply be `*` to scan all repositories in the
|
||||
project.
|
||||
- The path within each repository to find the catalog YAML file. This will
|
||||
usually be `/catalog-info.yaml`, `/src/*/catalog-info.yaml` or a similar
|
||||
variation for catalog files stored in the root directory of each repository.
|
||||
|
||||
_Note:_ the path parameter follows the same rules as the search on Azure DevOps
|
||||
web interface. For more details visit the
|
||||
[official search documentation](https://docs.microsoft.com/en-us/azure/devops/project/search/get-started-search?view=azure-devops)
|
||||
@@ -165,6 +165,7 @@ common example being the `migrations` directory.
|
||||
Usage: backstage-cli backend:build [options]
|
||||
|
||||
Options:
|
||||
--minify Minify the generated code
|
||||
-h, --help display help for command
|
||||
```
|
||||
|
||||
@@ -371,6 +372,7 @@ the monorepo.
|
||||
Usage: backstage-cli plugin:build [options]
|
||||
|
||||
Options:
|
||||
--minify Minify the generated code
|
||||
-h, --help display help for command
|
||||
```
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ externalDocs:
|
||||
description: Backstage official documentation
|
||||
url: https://github.com/backstage/backstage/blob/master/docs/README.md
|
||||
servers:
|
||||
- url: http://localhost:7000/api/auth/
|
||||
- url: http://localhost:7007/api/auth/
|
||||
tags:
|
||||
- name: provider
|
||||
description: List of endpoints per provider
|
||||
|
||||
@@ -27,7 +27,7 @@ point building on top of the previous one:
|
||||
and the new APIs can be used in parallel. This deprecation must have been
|
||||
released for at least two weeks before the deprecated API is removed in a
|
||||
minor version bump.
|
||||
- **3** - The time limit for the deprecation is 3 months instead of two days.
|
||||
- **3** - The time limit for the deprecation is 3 months instead of two weeks.
|
||||
|
||||
TL;DR:
|
||||
|
||||
@@ -175,15 +175,6 @@ Utilities for writing tests for Backstage plugins and apps.
|
||||
|
||||
Stability: `2`
|
||||
|
||||
### `test-utils-core` [GitHub](https://github.com/backstage/backstage/tree/master/packages/test-utils-core/)
|
||||
|
||||
Internal testing utilities that are separated out for usage in
|
||||
@backstage/core-app-api and @backstage/core-plugin-api. All exports are
|
||||
re-exported by @backstage/test-utils. This package should not be depended on
|
||||
directly.
|
||||
|
||||
Stability: See @backstage/test-utils
|
||||
|
||||
### `theme` [GitHub](https://github.com/backstage/backstage/tree/master/packages/theme/)
|
||||
|
||||
The core Backstage MUI theme along with customization utilities.
|
||||
|
||||
@@ -261,10 +261,13 @@ analytics events captured.
|
||||
Use it like this:
|
||||
|
||||
```tsx
|
||||
import { ApiProvider, ApiRegistry } from '@backstage/core-app-api';
|
||||
import { analyticsApiRef } from '@backstage/core-plugin-api';
|
||||
import { MockAnalyticsApi, wrapInTestApp } from '@backstage/test-utils';
|
||||
import { render, fireEvent, waitFor } from '@testing-library/react';
|
||||
import { analyticsApiRef } from '@backstage/core-plugin-api';
|
||||
import {
|
||||
MockAnalyticsApi,
|
||||
TestApiProvider,
|
||||
wrapInTestApp,
|
||||
} from '@backstage/test-utils';
|
||||
|
||||
describe('SomeComponent', () => {
|
||||
it('should capture event on click', () => {
|
||||
@@ -274,9 +277,9 @@ describe('SomeComponent', () => {
|
||||
// Render the component being tested
|
||||
const { getByText } = render(
|
||||
wrapInTestApp(
|
||||
<ApiProvider apis={ApiRegistry.from([[analyticsApiRef, apiSpy]])}>
|
||||
<TestApiProvider apis={[[analyticsApiRef, apiSpy]]}>
|
||||
<SomeComponentUnderTest />
|
||||
</ApiProvider>,
|
||||
</TestApiProvider>,
|
||||
),
|
||||
);
|
||||
|
||||
|
||||
@@ -44,11 +44,11 @@ cd plugins/carmen-backend
|
||||
yarn start
|
||||
```
|
||||
|
||||
This will think for a bit, and then say `Listening on :7000`. In a different
|
||||
This will think for a bit, and then say `Listening on :7007`. In a different
|
||||
terminal window, now run
|
||||
|
||||
```sh
|
||||
curl localhost:7000/carmen/health
|
||||
curl localhost:7007/carmen/health
|
||||
```
|
||||
|
||||
This should return `{"status":"ok"}`. Success! Press `Ctrl + c` to kill it
|
||||
@@ -107,7 +107,7 @@ root), you should be able to fetch data from it.
|
||||
|
||||
```sh
|
||||
# Note the extra /api here
|
||||
curl localhost:7000/api/carmen/health
|
||||
curl localhost:7007/api/carmen/health
|
||||
```
|
||||
|
||||
This should return `{"status":"ok"}` like before. Success!
|
||||
|
||||
@@ -0,0 +1,68 @@
|
||||
---
|
||||
id: backend-to-backend-auth
|
||||
title: Backend-to-Backend Authentication
|
||||
description:
|
||||
Guide for authenticating API requests between Backstage plugin backends
|
||||
---
|
||||
|
||||
This tutorial describes the steps needed to handle _backend-to-backend
|
||||
authentication_, which allows plugin backends to determine whether a given
|
||||
request originates from a legitimate Backstage backend by verifying a token
|
||||
signed with a shared secret. This system has limited use for now, but will be
|
||||
needed to support the upcoming framework for permissions and authorization (see
|
||||
[the PRFC on the topic](https://github.com/backstage/backstage/pull/7761) for
|
||||
more details).
|
||||
|
||||
Backends have no concept of a Backstage identity, so instead they use a token
|
||||
generated using a shared key stored in config. You can generate a unique key for
|
||||
your app in a terminal, and set the `BACKEND_SECRET` environment variable to the
|
||||
resulting value.
|
||||
|
||||
```bash
|
||||
node -p 'require("crypto").randomBytes(24).toString("base64")'
|
||||
```
|
||||
|
||||
Requests originating from a backend plugin can be authenticated by decorating
|
||||
them with a backend token. Backend tokens can be generated using a
|
||||
`TokenManager`, which can be passed to plugin backends via the
|
||||
`PluginEnvironment`. The `TokenManager` provided in new Backstage instances
|
||||
generated by `create-app` is a stub, which returns empty tokens and accepts any
|
||||
input string as valid. To enable backend-to-backend authentication, you'll need
|
||||
to instantiate a new one using the secret from your config instead:
|
||||
|
||||
```diff
|
||||
// packages/backend/src/index.ts
|
||||
|
||||
function makeCreateEnv(config: Config) {
|
||||
const root = getRootLogger();
|
||||
const reader = UrlReaders.default({ logger: root, config });
|
||||
const discovery = SingleHostDiscovery.fromConfig(config);
|
||||
|
||||
root.info(`Created UrlReader ${reader}`);
|
||||
|
||||
const cacheManager = CacheManager.fromConfig(config);
|
||||
const databaseManager = DatabaseManager.fromConfig(config);
|
||||
- const tokenManager = ServerTokenManager.noop();
|
||||
+ const tokenManager = ServerTokenManager.fromConfig(config);
|
||||
```
|
||||
|
||||
With this `tokenManager`, you can then generate a server token for requests:
|
||||
|
||||
```typescript
|
||||
const { token } = await this.tokenManager.getToken();
|
||||
|
||||
const response = await fetch(pluginBackendApiUrl, {
|
||||
method: 'GET',
|
||||
headers: {
|
||||
...headers,
|
||||
Authorization: `Bearer ${token}`,
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
You can use the same `tokenManager` to authenticate tokens supplied on incoming
|
||||
requests:
|
||||
|
||||
```typescript
|
||||
await tokenManager.authenticate(token); // throws if token is invalid
|
||||
```
|
||||
Reference in New Issue
Block a user