paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 27 Packages Projects Releases Wiki Activity

Merge branch 'master' into rugvip/test-port

Browse Source
This commit is contained in:
Patrik Oldsberg
2021-11-22 17:33:10 +01:00
committed by GitHub
parent 29ef695410 9f9ff42e28
commit 8a96019a39
606 changed files with 10288 additions and 2245 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture-decisions/adr012-use-luxon-locale-and-date-presets.md
+1 -1
View File
@@ -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
---
docs/assets/features/techdocs/techdocs-cli-serve-preview.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 278 KiB

docs/auth/add-auth-provider.md
+1 -1
View File
@@ -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.
docs/auth/atlassian/provider.md
+1 -1
View File
@@ -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`
docs/auth/auth0/provider.md
+1 -1
View File
@@ -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
docs/auth/bitbucket/provider.md
+1 -1
View File
@@ -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**
docs/auth/github/provider.md
+1 -1
View File
@@ -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
docs/auth/gitlab/provider.md
+1 -1
View File
@@ -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
docs/auth/google/provider.md
+1 -1
View File
@@ -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
docs/auth/microsoft/provider.md
+1 -1
View File
@@ -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
docs/auth/okta/provider.md
+2 -2
View File
@@ -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
docs/auth/onelogin/provider.md
+1 -1
View File
@@ -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`
docs/conf/writing.md
+2 -2
View File
@@ -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
docs/deployment/docker.md
+4 -4
View File
@@ -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
docs/deployment/k8s.md
+7 -7
View File
@@ -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
```
docs/features/software-templates/writing-custom-actions.md
+6 -17
View File
@@ -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,
docs/features/software-templates/writing-templates.md
+2 -2
View File
@@ -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
docs/features/techdocs/cli.md
+241
View File
@@ -0,0 +1,241 @@
# TechDocs CLI
Utility command line interface for managing TechDocs sites in
[Backstage](https://github.com/backstage/backstage).
https://backstage.io/docs/features/techdocs/techdocs-overview
## Features
- Supports local development/preview of a TechDocs site in a Backstage app.
- Supports generation and publishing of a documentation site in a CI/CD
workflow.
```bash
techdocs-cli --help
Usage: techdocs-cli [options] [command]
Options:
-V, --version output the version number
-h, --help display help for command
Commands:
generate|build [options] Generate TechDocs documentation site using mkdocs.
publish [options] Publish generated TechDocs site to an external storage AWS S3,
Google GCS, etc.
serve:mkdocs [options] Serve a documentation project locally using mkdocs serve.
serve [options] Serve a documentation project locally in a Backstage app-like
environment
help [command] display help for command
```
## Installation
You can always use [`npx`](https://github.com/npm/npx) to run the latest version
of `techdocs-cli` -
```bash
npx @techdocs/cli [command]
```
Or you can install it using [npm](https://www.npmjs.com/package/@techdocs/cli) -
```bash
npm install -g @techdocs/cli
techdocs-cli [command]
```
## Usage
### Preview TechDocs site locally in a Backstage like environment
```bash
techdocs-cli serve
```
![A preview of techdocs-cli serve command](../../assets/features/techdocs/techdocs-cli-serve-preview.png)
By default, Docker and
[techdocs-container](https://github.com/backstage/techdocs-container) is used to
make sure all the dependencies are installed. However, Docker can be disabled
with `--no-docker` flag.
The command starts two local servers - an MkDocs preview server on port 8000 and
a Backstage app server on port 3000. The Backstage app has a custom TechDocs API
implementation, which uses the MkDocs preview server as a proxy to fetch the
generated documentation files and assets.
NOTE: When using a custom `techdocs` docker image, make sure the entry point is
also `ENTRYPOINT ["mkdocs"]`.
Command reference:
```bash
Usage: techdocs-cli serve [options]
Serve a documentation project locally in a Backstage app-like environment
Options:
-i, --docker-image <DOCKER_IMAGE> The mkdocs docker container to use (default: "spotify/techdocs")
--no-docker Do not use Docker, use MkDocs executable in current user environment.
--mkdocs-port <PORT> Port for MkDocs server to use (default: "8000")
-v --verbose Enable verbose output. (default: false)
-h, --help display help for command
```
### Generate TechDocs site from a documentation project
```bash
techdocs-cli generate
```
Alias: `techdocs-cli build`
The generate command uses the
[`@backstage/techdocs-common`](https://github.com/backstage/backstage/tree/master/packages/techdocs-common)
package from Backstage for consistency. A Backstage app can also generate and
publish TechDocs sites if `techdocs.builder` is set to `'local'` in
`app-config.yaml`. See
[configuration reference](https://backstage.io/docs/features/techdocs/configuration).
By default, this command uses Docker and
[techdocs-container](https://github.com/backstage/techdocs-container) to make
sure all the dependencies are installed. But it can be disabled using
`--no-docker` flag.
Command reference:
```bash
techdocs-cli generate --help
Usage: techdocs-cli generate|build [options]
Generate TechDocs documentation site using MkDocs.
Options:
--source-dir <PATH> Source directory containing mkdocs.yml and docs/ directory. (default: ".")
--output-dir <PATH> Output directory containing generated TechDocs site. (default: "./site/")
--docker-image <DOCKER_IMAGE> The mkdocs docker container to use (default: "spotify/techdocs:v0.3.4")
--no-pull Do not pull the latest docker image
--no-docker Do not use Docker, use MkDocs executable and plugins in current user environment.
--techdocs-ref <HOST_TYPE:URL> The repository hosting documentation source files e.g.
github:https://ghe.mycompany.net.com/org/repo.
This value is same as the backstage.io/techdocs-ref annotation of the corresponding
Backstage entity.
It is completely fine to skip this as it is only being used to set repo_url in mkdocs.yml
if not found.
--etag <ETAG> A unique identifier for the prepared tree e.g. commit SHA. If provided it will be stored
in techdocs_metadata.json.
-v --verbose Enable verbose output. (default: false)
-h, --help display help for command
```
### Publish generated TechDocs sites
```bash
techdocs-cli publish --publisher-type <awsS3|googleGcs|azureBlobStorage> --storage-name <bucket/container name> --entity <namespace/kind/name>
```
After generating a TechDocs site using `techdocs-cli generate`, use the publish
command to upload the static generated files on a cloud storage (AWS/GCS) bucket
or (Azure) container which your Backstage app can read from.
The value for `--entity` must be the Backstage entity which the generated
TechDocs site belongs to. You can find the values in your Entity's
`catalog-info.yaml` file. If namespace is missing in the `catalog-info.yaml`,
use `default`. The directory structure used in the storage bucket is
`namespace/kind/name/<files>`.
Note that the values are case-sensitive. An example for `--entity` is
`default/Component/<entityName>`.
Command reference:
```bash
Usage: techdocs-cli publish [options]
Publish generated TechDocs site to an external storage AWS S3, Google GCS, etc.
Options:
--publisher-type <TYPE> (Required always) awsS3 | googleGcs | azureBlobStorage
- same as techdocs.publisher.type in Backstage
app-config.yaml
--storage-name <BUCKET/CONTAINER NAME> (Required always) In case of AWS/GCS, use the bucket
name. In case of Azure, use container name. Same as
techdocs.publisher.[TYPE].bucketName
--entity <NAMESPACE/KIND/NAME> (Required always) Entity uid separated by / in
namespace/kind/name order (case-sensitive). Example:
default/Component/myEntity
--legacyUseCaseSensitiveTripletPaths Publishes objects with cased entity triplet prefix when set (e.g. namespace/Kind/name).
Only use if your TechDocs backend is configured the same way
--azureAccountName <AZURE ACCOUNT NAME> (Required for Azure) specify when --publisher-type
azureBlobStorage
--azureAccountKey <AZURE ACCOUNT KEY> Azure Storage Account key to use for authentication.
If not specified, you must set AZURE_TENANT_ID,
AZURE_CLIENT_ID & AZURE_CLIENT_SECRET as environment
variables.
--awsRoleArn <AWS ROLE ARN> Optional AWS ARN of role to be assumed.
--awsEndpoint <AWS ENDPOINT> Optional AWS endpoint to send requests to.
--awsS3ForcePathStyle Optional AWS S3 option to force path style.
--directory <PATH> Path of the directory containing generated files to
publish (default: "./site/")
-h, --help display help for command
```
### Migrate content for case-insensitive access
Prior to the beta version of TechDocs (`v[0.11.0]`), TechDocs were stored in
object storage using a case-sensitive entity triplet (e.g.
`default/API/name/index.html`). This resulted in a limitation where that exact
case was required in the Backstage URL in order to read/render TechDocs content.
As of `v[0.11.0]` of the TechDocs plugin, any case is allowed in the URL (e.g.
`default/api/name`), matching the behavior of the Catalog plugin.
Backstage instances created with TechDocs `v[0.11.0]` or later do not need this
command. However, when upgrading to this version from an older version of
TechDocs, the `migrate` command can be used prior to deployment to ensure docs
remain accessible without having to rebuild all docs.
Prior to upgrading to `v[0.11.0]` or greater, run this command to copy all
assets to their lower-case triplet equivalents like this:
```bash
techdocs-cli migrate --publisher-type <awsS3|googleGcs|azureBlobStorage> --storage-name <bucket/container name> --verbose
```
Once migrated and the upgraded version of the Backstage plugin has been
deployed, you can clean up the legacy, case-sensitive triplet files by
re-running the command with the `--removeOriginal` flag passed, which _moves_
(rather than copies) the files. Note: this deletes files and is therefore a
destructive operation that should performed with caution.
```bash
techdocs-cli migrate --publisher-type <awsS3|googleGcs|azureBlobStorage> --storage-name <bucket/container name> --removeOriginal --verbose
```
Afterward, update your TechDocs CLI to `v[0.7.0]` to ensure further publishing
happens using a lower-case entity triplet.
Note: arguments for this command largely match those of the `publish` command,
depending on your chosen storage provider. Run `techdocs-cli migrate --help` for
details.
#### Authentication
You need to make sure that your environment is able to authenticate with the
target cloud provider. `techdocs-cli` uses the official Node.js clients provided
by AWS (v2), Google Cloud and Azure. You can authenticate using environment
variables and/or by other means (`~/.aws/credentials`, `~/.config/gcloud` etc.)
Refer to the Authentication section of the following documentation depending
upon your cloud storage provider -
- [Google Cloud Storage](https://backstage.io/docs/features/techdocs/using-cloud-storage#configuring-google-gcs-bucket-with-techdocs)
- [AWS S3](https://backstage.io/docs/features/techdocs/using-cloud-storage#configuring-aws-s3-bucket-with-techdocs)
- [Azure Blob Storage](https://backstage.io/docs/features/techdocs/using-cloud-storage#configuring-azure-blob-storage-container-with-techdocs)
## Development
You are welcome to contribute to TechDocs CLI to improve it and support new
features! See the project
[README](https://github.com/backstage/backstage/blob/main/src/packages/techdocs-cli/README.md)
for more information.
docs/features/techdocs/configuration.md
+2 -2
View File
@@ -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
```
docs/getting-started/contributors.md
+1 -1
View File
@@ -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.
docs/getting-started/index.md
+1 -1
View File
@@ -37,7 +37,7 @@ guide to do a repository-based installation.
- `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
ports need to be opened: 3000, 7007
### Create your Backstage App
docs/getting-started/running-backstage-locally.md
+1 -1
View File
@@ -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.
docs/openapi/definitions/auth.yaml
+1 -1
View File
@@ -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
docs/plugins/backend-plugin.md
+3 -3
View File
@@ -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!