Merge branch 'master' into scorecard-tech-insights
Signed-off-by: irma12 <irma@roadie.io>
This commit is contained in:
irma12
@@ -0,0 +1,6 @@
|
||||
---
|
||||
'@backstage/errors': patch
|
||||
---
|
||||
|
||||
Deprecate `parseErrorResponse` in favour of `parseErrorResponseBody`. Deprecate `data` field inside `ErrorResponse` in favour of `body`.
|
||||
Rename the error name for unknown errors from `unknown` to `error`.
|
||||
@@ -23,13 +23,13 @@ const {
|
||||
async function getDependencyReleaseLine(changesets, dependenciesUpdated) {
|
||||
if (dependenciesUpdated.length === 0) return '';
|
||||
|
||||
const updatedDepenenciesList = dependenciesUpdated.map(
|
||||
const updatedDependenciesList = dependenciesUpdated.map(
|
||||
dependency => ` - ${dependency.name}@${dependency.newVersion}`,
|
||||
);
|
||||
|
||||
// Return one `Updated dependencies` bullet instead of repeating for each changeset; this
|
||||
// sacrifices the commit shas for brevity.
|
||||
return ['- Updated dependencies', ...updatedDepenenciesList].join('\n');
|
||||
return ['- Updated dependencies', ...updatedDependenciesList].join('\n');
|
||||
}
|
||||
|
||||
module.exports = {
|
||||
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/dev-utils': patch
|
||||
---
|
||||
|
||||
Add theme switcher to sidebar of dev app.
|
||||
@@ -1,6 +0,0 @@
|
||||
---
|
||||
'@backstage/plugin-catalog': patch
|
||||
---
|
||||
|
||||
Remove the "View Api" icon in the AboutCard, as the information is misleading for some users and is
|
||||
duplicated in the tabs above.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/plugin-cost-insights': patch
|
||||
---
|
||||
|
||||
Fixed generation of sample data in the example Cost Insights client
|
||||
@@ -0,0 +1,6 @@
|
||||
---
|
||||
'@backstage/plugin-tech-insights-backend': patch
|
||||
'@backstage/plugin-tech-insights-backend-module-jsonfc': patch
|
||||
---
|
||||
|
||||
Update README docs to use correct function/parameter names
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/catalog-client': patch
|
||||
---
|
||||
|
||||
Update to the right version of @backstage/errors
|
||||
@@ -0,0 +1,5 @@
|
||||
---
|
||||
'@backstage/plugin-scaffolder': patch
|
||||
---
|
||||
|
||||
Bump `react-jsonschema-form`
|
||||
@@ -1,19 +0,0 @@
|
||||
---
|
||||
'@backstage/plugin-gcp-projects': patch
|
||||
---
|
||||
|
||||
UI updates to GCP-projects plugin
|
||||
|
||||
Adds the following to the project list page:
|
||||
|
||||
- pagination
|
||||
- filtering
|
||||
- sorting
|
||||
- rows per page
|
||||
- show/hide columns
|
||||
|
||||
Makes breadcrumb a link back to project list for the project details and new project views.
|
||||
|
||||
In project list page, updates New project button to use RouterLink instead of `href` to avoid login prompt.
|
||||
|
||||
In project details view, links to project details and logs now work, clicking on these will open the project or logs in GCP in new tab.
|
||||
@@ -1,8 +0,0 @@
|
||||
---
|
||||
'@backstage/catalog-model': patch
|
||||
'@backstage/cli': patch
|
||||
'@backstage/config-loader': patch
|
||||
'@backstage/plugin-scaffolder': patch
|
||||
---
|
||||
|
||||
Update the json-schema dependency version.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/cli': patch
|
||||
---
|
||||
|
||||
remove double config dep
|
||||
@@ -0,0 +1,5 @@
|
||||
---
|
||||
'@backstage/plugin-auth-backend': patch
|
||||
---
|
||||
|
||||
Switched to using the standardized JSON error responses for all provider endpoints.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/plugin-kafka-backend': patch
|
||||
---
|
||||
|
||||
Update Kafka configuration types
|
||||
@@ -0,0 +1,5 @@
|
||||
---
|
||||
'@backstage/cli': patch
|
||||
---
|
||||
|
||||
Switch the default test coverage provider from the jest default one to `'v8'`, which provides much better coverage information when using the default Backstage test setup. This is considered a bug fix as the current coverage information is often very inaccurate.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/dev-utils': patch
|
||||
---
|
||||
|
||||
Migrated to using `@backstage/app-defaults`.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/backend-common': patch
|
||||
---
|
||||
|
||||
Added the `isDatabaseConflictError` function.
|
||||
@@ -1,13 +0,0 @@
|
||||
---
|
||||
'@backstage/create-app': patch
|
||||
---
|
||||
|
||||
Migrated the app template use the new `@backstage/app-defaults` for the `createApp` import, since the `createApp` exported by `@backstage/app-core-api` will be removed in the future.
|
||||
|
||||
To migrate an existing application, add the latest version of `@backstage/app-defaults` as a dependency in `packages/app/package.json`, and make the following change to `packages/app/src/App.tsx`:
|
||||
|
||||
```diff
|
||||
-import { createApp, FlatRoutes } from '@backstage/core-app-api';
|
||||
+import { createApp } from '@backstage/app-defaults';
|
||||
+import { FlatRoutes } from '@backstage/core-app-api';
|
||||
```
|
||||
@@ -1,6 +0,0 @@
|
||||
---
|
||||
'@backstage/core-components': patch
|
||||
'@backstage/plugin-user-settings': patch
|
||||
---
|
||||
|
||||
Add Props Icon for Sidebar Item SidebarSearchField and Settings
|
||||
@@ -0,0 +1,5 @@
|
||||
---
|
||||
'@backstage/cli': patch
|
||||
---
|
||||
|
||||
Disable ES transforms in tests transformed by the `jestSucraseTransform.js`. This is not considered a breaking change since all code is already transpiled this way in the development setup.
|
||||
@@ -0,0 +1,5 @@
|
||||
---
|
||||
'@backstage/create-app': patch
|
||||
---
|
||||
|
||||
DefaultTechDocsCollator is now included in the search backend, and the Search Page updated with the SearchType component that includes the techdocs type
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/core-components': patch
|
||||
---
|
||||
|
||||
Changing the `Header` styles to use more theme variables. With this the title `font-size` will not change on resizing the window.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/create-app': patch
|
||||
---
|
||||
|
||||
Refactor and add regression tests for create-app tasks
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/cli': minor
|
||||
---
|
||||
|
||||
Tweaked style insertion logic to make sure that JSS stylesheets always receive the highest priority.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/backend-common': patch
|
||||
---
|
||||
|
||||
Paths can be specified in backend.reading.allow to further restrict allowed targets
|
||||
@@ -1,6 +0,0 @@
|
||||
---
|
||||
'@backstage/core-app-api': patch
|
||||
'@backstage/test-utils': patch
|
||||
---
|
||||
|
||||
Migrated to using new `ErrorApiError` and `ErrorApiErrorContext` names.
|
||||
@@ -1,6 +0,0 @@
|
||||
---
|
||||
'@backstage/core-components': patch
|
||||
'@backstage/plugin-auth-backend': patch
|
||||
---
|
||||
|
||||
Update OAuthAdapter to create identity.token from identity.idToken if it does not exist, and prevent overwrites to identity.toke. Update login page commonProvider to prefer .token over .idToken
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/plugin-scaffolder-backend': patch
|
||||
---
|
||||
|
||||
Skip empty file names when scaffolding with nunjucks
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/plugin-catalog-backend': patch
|
||||
---
|
||||
|
||||
Adjust entity query construction to ensure sub-queries are always isolated from one another.
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
'@backstage/backend-common': patch
|
||||
'@backstage/cli': patch
|
||||
'@backstage/core-app-api': patch
|
||||
'@backstage/create-app': patch
|
||||
'@backstage/techdocs-common': patch
|
||||
'@backstage/plugin-auth-backend': patch
|
||||
'@backstage/plugin-azure-devops-backend': patch
|
||||
'@backstage/plugin-badges-backend': patch
|
||||
'@backstage/plugin-bazaar-backend': patch
|
||||
'@backstage/plugin-catalog-backend': patch
|
||||
'@backstage/plugin-code-coverage-backend': patch
|
||||
'@backstage/plugin-github-actions': patch
|
||||
'@backstage/plugin-jenkins-backend': patch
|
||||
'@backstage/plugin-proxy-backend': patch
|
||||
'@backstage/plugin-rollbar-backend': patch
|
||||
'@backstage/plugin-search-backend': patch
|
||||
'@backstage/plugin-techdocs': patch
|
||||
'@backstage/plugin-techdocs-backend': patch
|
||||
---
|
||||
|
||||
Change default port of backend from 7000 to 7007.
|
||||
|
||||
This is due to the AirPlay Receiver process occupying port 7000 and preventing local Backstage instances on MacOS to start.
|
||||
|
||||
You can change the port back to 7000 or any other value by providing an `app-config.yaml` with the following values:
|
||||
|
||||
```
|
||||
backend:
|
||||
listen: 0.0.0.0:7123
|
||||
baseUrl: http://localhost:7123
|
||||
```
|
||||
|
||||
More information can be found here: https://backstage.io/docs/conf/writing
|
||||
@@ -0,0 +1,5 @@
|
||||
---
|
||||
'@backstage/plugin-permission-common': minor
|
||||
---
|
||||
|
||||
Accept configApi rather than enabled flag in PermissionClient constructor.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/core-app-api': patch
|
||||
---
|
||||
|
||||
Deprecated the `BackstagePluginWithAnyOutput` type.
|
||||
@@ -1,12 +0,0 @@
|
||||
---
|
||||
'@backstage/backend-common': patch
|
||||
---
|
||||
|
||||
Make sure that server builder `start()` propagates errors (such as failing to bind to the required port) properly and doesn't resolve the promise prematurely.
|
||||
|
||||
After this change, the backend logger will be able to actually capture the error as it happens:
|
||||
|
||||
```
|
||||
2021-11-11T10:54:21.334Z backstage info Initializing http server
|
||||
2021-11-11T10:54:21.335Z backstage error listen EADDRINUSE: address already in use :::7000 code=EADDRINUSE errno=-48 syscall=listen address=:: port=7000
|
||||
```
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/core-app-api': patch
|
||||
---
|
||||
|
||||
Start exporting and marking several types as public to address errors in the API report.
|
||||
@@ -0,0 +1,6 @@
|
||||
---
|
||||
'@backstage/plugin-config-schema': patch
|
||||
'@backstage/plugin-scaffolder': patch
|
||||
---
|
||||
|
||||
Fixed a missing `await` when throwing server side errors
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/core-plugin-api': minor
|
||||
---
|
||||
|
||||
Removed the unused `UserFlags` type.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/core-plugin-api': patch
|
||||
---
|
||||
|
||||
Deprecated the `theme` property on `AppTheme`, replacing it with `Provider`. See https://backstage.io/docs/api/deprecations#app-theme for more details.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/cli': patch
|
||||
---
|
||||
|
||||
Added a scaffolder backend module template for the `create` command.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/core-plugin-api': minor
|
||||
---
|
||||
|
||||
Remove exports of unused types(`RouteOptions` and `RoutePath`).
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/test-utils': patch
|
||||
---
|
||||
|
||||
Migrated to using `createSpecializedApp`.
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
'@backstage/plugin-catalog-backend': minor
|
||||
---
|
||||
|
||||
**BREAKING** EntitiesSearchFilter fields have changed.
|
||||
|
||||
EntitiesSearchFilter now has only two fields: `key` and `value`. The `matchValueIn` and `matchValueExists` fields are no longer are supported. Previous filters written using the `matchValueIn` and `matchValueExists` fields can be rewritten as follows:
|
||||
|
||||
Filtering by existence of key only:
|
||||
|
||||
```diff
|
||||
filter: {
|
||||
{
|
||||
key: 'abc',
|
||||
- matchValueExists: true,
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Filtering by key and values:
|
||||
|
||||
```diff
|
||||
filter: {
|
||||
{
|
||||
key: 'abc',
|
||||
- matchValueExists: true,
|
||||
- matchValueIn: ['xyz'],
|
||||
+ values: ['xyz'],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Negation of filters can now be achieved through a `not` object:
|
||||
|
||||
```
|
||||
filter: {
|
||||
not: {
|
||||
key: 'abc',
|
||||
values: ['xyz'],
|
||||
},
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,5 @@
|
||||
---
|
||||
'@backstage/plugin-catalog-backend': patch
|
||||
---
|
||||
|
||||
Index User entities by displayName to be able to search by full name. Added displayName (if present) to the 'text' field in the indexed document.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/cli': patch
|
||||
---
|
||||
|
||||
Fixed a bug where calling `backstage-cli backend:bundle --build-dependencies` with no dependencies to be built would cause all monorepo packages to be built instead.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/backend-common': patch
|
||||
---
|
||||
|
||||
Do not redact empty or one-character strings. These imply that it's just a test or local dev, and unnecessarily ruin the log output.
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
'@backstage/plugin-azure-devops': patch
|
||||
'@backstage/plugin-azure-devops-backend': patch
|
||||
'@backstage/plugin-azure-devops-common': minor
|
||||
---
|
||||
|
||||
Improved Date handling for the Azure DevOps set of plugins by using strings and letting the frontend handle the conversion to DateTime
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/plugin-techdocs': patch
|
||||
---
|
||||
|
||||
Fixed entity triplet case handling for certain locales.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/techdocs-common': patch
|
||||
---
|
||||
|
||||
Added OpenStack Swift case migration support.
|
||||
@@ -1,6 +0,0 @@
|
||||
---
|
||||
'@backstage/techdocs-common': patch
|
||||
'@backstage/plugin-techdocs-backend': patch
|
||||
---
|
||||
|
||||
Allow amazon web services s3 buckets to pass an server side encryption configuration so they can publish to encrypted buckets
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/plugin-techdocs': patch
|
||||
---
|
||||
|
||||
Use a better checkbox rendering in a task list.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/cli': patch
|
||||
---
|
||||
|
||||
bump `@rollup/plugin-commonjs` from 17.1.0 to 21.0.1
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/cli': patch
|
||||
---
|
||||
|
||||
Introduces new `backstage-cli create` command to replace `create-plugin` and make space for creating a wider array of things. The create command also adds a new template for creating isomorphic common plugin packages.
|
||||
@@ -1,9 +0,0 @@
|
||||
---
|
||||
'@backstage/core-app-api': patch
|
||||
---
|
||||
|
||||
The `createApp` function from `@backstage/core-app-api` has been deprecated, with two new options being provided as a replacement.
|
||||
|
||||
The first and most commonly used one is `createApp` from the new `@backstage/app-defaults` package, which behaves just like the existing `createApp`. In the future this method is likely to be expanded to add more APIs and other pieces into the default setup, for example the Utility APIs from `@backstage/integration-react`.
|
||||
|
||||
The other option that we now provide is to use `createSpecializedApp` from `@backstage/core-app-api`. This is a more low-level API where you need to provide a full set of options, including your own `components`, `icons`, `defaultApis`, and `themes`. The `createSpecializedApp` way of creating an app is particularly useful if you are not using `@backstage/core-components` or MUI, as it allows you to avoid those dependencies completely.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/plugin-catalog-backend': patch
|
||||
---
|
||||
|
||||
adds getDefaultProcessor method to CatalogBuilder
|
||||
@@ -0,0 +1,5 @@
|
||||
---
|
||||
'@backstage/cli': patch
|
||||
---
|
||||
|
||||
Update the default routes to use id instead of title
|
||||
@@ -0,0 +1,63 @@
|
||||
---
|
||||
'@backstage/core-app-api': patch
|
||||
'@backstage/test-utils': patch
|
||||
---
|
||||
|
||||
The `ApiRegistry` from `@backstage/core-app-api` class has been deprecated and will be removed in a future release. To replace it, we have introduced two new helpers that are exported from `@backstage/test-utils`, namely `TestApiProvider` and `TestApiRegistry`.
|
||||
|
||||
These two new helpers are more tailored for writing tests and development setups, as they allow for partial implementations of each of the APIs.
|
||||
|
||||
When migrating existing code it is typically best to prefer usage of `TestApiProvider` when possible, so for example the following code:
|
||||
|
||||
```tsx
|
||||
render(
|
||||
<ApiProvider
|
||||
apis={ApiRegistry.from([
|
||||
[identityApiRef, mockIdentityApi as unknown as IdentityApi]
|
||||
])}
|
||||
>
|
||||
{...}
|
||||
</ApiProvider>
|
||||
)
|
||||
```
|
||||
|
||||
Would be migrated to this:
|
||||
|
||||
```tsx
|
||||
render(
|
||||
<TestApiProvider apis={[[identityApiRef, mockIdentityApi]]}>
|
||||
{...}
|
||||
</TestApiProvider>
|
||||
)
|
||||
```
|
||||
|
||||
In cases where the `ApiProvider` is used in a more standalone way, for example to reuse a set of APIs across multiple tests, the `TestApiRegistry` can be used instead. Note that the `TestApiRegistry` only has a single static factory method, `.from()`, and it is slightly different from the existing `.from()` method on `ApiRegistry` in that it doesn't require the API pairs to be wrapped in an outer array.
|
||||
|
||||
Usage that looks like this:
|
||||
|
||||
```ts
|
||||
const apis = ApiRegistry.with(
|
||||
identityApiRef,
|
||||
mockIdentityApi as unknown as IdentityApi,
|
||||
).with(configApiRef, new ConfigReader({}));
|
||||
```
|
||||
|
||||
OR like this:
|
||||
|
||||
```ts
|
||||
const apis = ApiRegistry.from([
|
||||
[identityApiRef, mockIdentityApi as unknown as IdentityApi],
|
||||
[configApiRef, new ConfigReader({})],
|
||||
]);
|
||||
```
|
||||
|
||||
Would be migrated to this:
|
||||
|
||||
```ts
|
||||
const apis = TestApiRegistry.from(
|
||||
[identityApiRef, mockIdentityApi],
|
||||
[configApiRef, new ConfigReader({})],
|
||||
);
|
||||
```
|
||||
|
||||
If your app is still using the `ApiRegistry` to construct the `apis` for `createApp`, we recommend that you move over to use the new method of supplying API factories instead, using `createApiFactory`.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
'@backstage/core-plugin-api': patch
|
||||
---
|
||||
|
||||
Deprecated the `Error` and `ErrorContext` types, replacing them with identical `ErrorApiError` and `ErrorApiErrorContext` types.
|
||||
@@ -0,0 +1,5 @@
|
||||
---
|
||||
'@backstage/core-components': patch
|
||||
---
|
||||
|
||||
Pin sidebar by default for easier navigation
|
||||
@@ -0,0 +1,5 @@
|
||||
---
|
||||
'@backstage/plugin-graphiql': patch
|
||||
---
|
||||
|
||||
Letting GraphiQL use headers
|
||||
@@ -18,7 +18,9 @@
|
||||
/plugins/techdocs-backend @backstage/techdocs-core
|
||||
/plugins/ilert @backstage/reviewers @yacut
|
||||
/plugins/home @backstage/techdocs-core
|
||||
/packages/embedded-techdocs-app @backstage/techdocs-core
|
||||
/packages/search-common @backstage/techdocs-core
|
||||
/packages/techdocs-cli @backstage/techdocs-core
|
||||
/packages/techdocs-common @backstage/techdocs-core
|
||||
/.changeset/cost-insights-* @backstage/reviewers @backstage/silver-lining
|
||||
/.changeset/search-* @backstage/techdocs-core
|
||||
|
||||
@@ -63,6 +63,7 @@ Debounce
|
||||
declaratively
|
||||
deduplicated
|
||||
deps
|
||||
dependabot
|
||||
destructured
|
||||
dev
|
||||
devops
|
||||
|
||||
@@ -6,6 +6,8 @@ on:
|
||||
|
||||
jobs:
|
||||
sync:
|
||||
if: github.repository == 'backstage/backstage' # prevent running on forks
|
||||
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
strategy:
|
||||
|
||||
@@ -0,0 +1,42 @@
|
||||
name: Techdocs E2E Test
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
paths-ignore:
|
||||
- '.changeset/**'
|
||||
- 'contrib/**'
|
||||
- 'docs/**'
|
||||
- 'microsite/**'
|
||||
|
||||
jobs:
|
||||
verify:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
strategy:
|
||||
matrix:
|
||||
node-version: [14.x, 16.x]
|
||||
|
||||
env:
|
||||
CI: true
|
||||
NODE_OPTIONS: --max-old-space-size=4096
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
- uses: actions/setup-python@v2
|
||||
|
||||
- name: install dependencies
|
||||
run: yarn install --frozen-lockfile
|
||||
|
||||
- name: generate types
|
||||
run: yarn tsc
|
||||
|
||||
- name: build techdocs-cli
|
||||
working-directory: packages/techdocs-cli
|
||||
run: yarn build
|
||||
|
||||
- name: Install mkdocs & techdocs-core
|
||||
run: python -m pip install mkdocs-techdocs-core
|
||||
|
||||
- name: techdocs-cli e2e test
|
||||
working-directory: packages/techdocs-cli
|
||||
run: yarn test:e2e:ci
|
||||
+2
-2
@@ -1,7 +1,7 @@
|
||||
services:
|
||||
backstage:
|
||||
image: tugboatqa/node:lts
|
||||
expose: 7000
|
||||
expose: 7007
|
||||
default: true
|
||||
commands:
|
||||
init:
|
||||
@@ -14,4 +14,4 @@ services:
|
||||
- yarn workspace example-app build
|
||||
start:
|
||||
# wget the endpoint. Will retry every 2 seconds. 30 retries = 1m for service to come up. Plenty.
|
||||
- wget -O /dev/null -o /dev/null --tries=30 --timeout=5 --retry-connrefused http://localhost:7000
|
||||
- wget -O /dev/null -o /dev/null --tries=30 --timeout=5 --retry-connrefused http://localhost:7007
|
||||
|
||||
+5
-2
@@ -66,5 +66,8 @@
|
||||
| [Palo Alto Networks](https://www.paloaltonetworks.com) | [Jeremy Guarini](https://github.com/jeremyguarini), [Brian Lomeland](https://github.com/bbbmmmlll), [Palo Alto Networks](https://github.com/PaloAltoNetworks) | Developer portal, service catalog, documentation and tooling |
|
||||
| [Signal Iduna Group](https://www.signal-iduna.de/) | [Jonas Thomsen](https://github.com/JoThomsen) | Developer Portal, documentation, monitoring, service catalog for our insurance ecosystem |
|
||||
| [Tradeshift](https://www.tradeshift.com/) | [Soren Mathiasen](https://github.com/sorenmat) | Developer Portal: documentation, monitoring, service templates, service catalog for our micro services |
|
||||
| [Unity](https://unity.com) | [Ted Cordery](https://github.com/TeddyBallGame) | A centralized service catalog with documentation for our service engineers. |
|
||||
| [PicPay](https://www.picpay.com) | [Luis Baroni](https://github.com/lcsbaroni), [Renata Poluceno](https://github.com/renatapoluceno), [PicPay](https://github.com/picpay) | Developer portal for building services throught templates, service catalog with ownership of services, documentation and metrics providing autonomy and visibility for all. |
|
||||
| [Unity](https://unity.com) | [Ted Cordery](https://github.com/TeddyBallGame) | A centralized service catalog with documentation for our service engineers. |
|
||||
| [PicPay](https://www.picpay.com) | [Luis Baroni](https://github.com/lcsbaroni), [Renata Poluceno](https://github.com/renatapoluceno), [PicPay](https://github.com/picpay) | Developer portal for building services throught templates, service catalog with ownership of services, documentation and metrics providing autonomy and visibility for all. |
|
||||
| [Epic Games](https://www.epicgames.com) | [Brian Jung](https://github.com/brian-at-epic), [Jeff Goldian](https://github.com/jeffgoldian-Epic) | Developer Portal: Service Catalog, Documentation, Software Templates and more making our internal teams' lives easier! |
|
||||
| [Globo](https://globo.com) | [Carlos Gusmão](https://github.com/caeugusmao), [Guilherme Vierno](https://github.com/vierno), [Denis Aoki](https://github.com/dnsaoki2), [Maycon Dionisio](https://github.com/MayconDionisio), | Reduce the friction of accessing the information engineers need about Globo's digital services through a coherent and centralized experience. |
|
||||
| [QBE](https://www.qbe.com/) | [Daniel Steel](https://github.com/danielsteelqbe), [Pete Jespers](https://github.com/petejespersqbe) | Developer portal allowing our global teams to explore and create applications, documentation and cloud infrastructure easily and quickly 🚀 |
|
||||
|
||||
+3
-1
@@ -122,7 +122,9 @@ We use [changesets](https://github.com/atlassian/changesets) to help us prepare
|
||||
|
||||
Any time a patch, minor, or major change aligning to [Semantic Versioning](https://semver.org) is made to any published package in `packages/` or `plugins/`, a changeset should be used. It helps to align your change to the [Backstage stability index](https://backstage.io/docs/overview/stability-index) for the package you are changing, for example, when to provide additional clarity on deprecation or impacting changes which will then be included into CHANGELOGs.
|
||||
|
||||
In general, changesets are not needed for the documentation, build utilities, contributed samples in `contrib/`, or the [example `packages/app`](packages/app).
|
||||
In general, changesets are only needed for changes to packages within `packages/` or `plugins/` directories, and only for the packages that are not marked as `private`. Changesets are also not needed for changes that do not affect the published version of each package, for example changes to tests or in-line source code comments.
|
||||
|
||||
Changesets **are** needed for new packages, as that is what triggers the package to be part of the next release.
|
||||
|
||||
### How to create a changeset
|
||||
|
||||
|
||||
+2
-2
@@ -23,9 +23,9 @@ app:
|
||||
title: '#backstage'
|
||||
|
||||
backend:
|
||||
baseUrl: http://localhost:7000
|
||||
baseUrl: http://localhost:7007
|
||||
listen:
|
||||
port: 7000
|
||||
port: 7007
|
||||
database:
|
||||
client: sqlite3
|
||||
connection: ':memory:'
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
backend:
|
||||
lighthouseHostname: {{ include "lighthouse.serviceName" . | quote }}
|
||||
listen:
|
||||
port: {{ .Values.appConfig.backend.listen.port | default 7000 }}
|
||||
port: {{ .Values.appConfig.backend.listen.port | default 7007 }}
|
||||
database:
|
||||
client: {{ .Values.appConfig.backend.database.client | quote }}
|
||||
connection:
|
||||
|
||||
@@ -26,7 +26,7 @@ backend:
|
||||
repository: martinaif/backstage-k8s-demo-backend
|
||||
tag: 20210423T1550
|
||||
pullPolicy: IfNotPresent
|
||||
containerPort: 7000
|
||||
containerPort: 7007
|
||||
serviceType: ClusterIP
|
||||
postgresCertMountEnabled: true
|
||||
resources:
|
||||
@@ -96,7 +96,7 @@ appConfig:
|
||||
backend:
|
||||
baseUrl: https://demo.example.com
|
||||
listen:
|
||||
port: 7000
|
||||
port: 7007
|
||||
cors:
|
||||
origin: https://demo.example.com
|
||||
database:
|
||||
|
||||
@@ -9,8 +9,8 @@ docker_name_prefix := backstage-make
|
||||
# to the host computer
|
||||
frontend_port := 3000
|
||||
frontend_host_port := 3000
|
||||
backend_port := 7000
|
||||
backend_host_port := 7000
|
||||
backend_port := 7007
|
||||
backend_host_port := 7007
|
||||
|
||||
# path to this "makefile"
|
||||
my_dir_path = $(dir $(CURDIR)/$(firstword $(words $(MAKEFILE_LIST)),$(MAKEFILE_LIST)))
|
||||
@@ -191,10 +191,10 @@ test: check-tests
|
||||
check: check-code check-docs check-type-dependencies check-styles
|
||||
|
||||
# run development instance
|
||||
# BUG: the frontend seems to run on "$(backend_port)" (7000 default).
|
||||
# BUG: the frontend seems to run on "$(backend_port)" (7007 default).
|
||||
# The documentation states "This is going to start two things,
|
||||
# the frontend (:3000) and the backend (:7000)."
|
||||
# However, the frontend seems to end up running on 7000.
|
||||
# the frontend (:3000) and the backend (:7007)."
|
||||
# However, the frontend seems to end up running on 7007.
|
||||
.PHONY: dev
|
||||
dev: build
|
||||
@docker run --rm -it \
|
||||
|
||||
@@ -22,6 +22,6 @@ spec:
|
||||
image: spotify/backstage-backend:latest
|
||||
imagePullPolicy: IfNotPresent
|
||||
ports:
|
||||
- containerPort: 7000
|
||||
- containerPort: 7007
|
||||
name: backend
|
||||
protocol: TCP
|
||||
|
||||
@@ -63,7 +63,7 @@ backend:
|
||||
pullPolicy: IfNotPresent
|
||||
service:
|
||||
type: ClusterIP
|
||||
port: 7000
|
||||
port: 7007
|
||||
ingress:
|
||||
enabled: false
|
||||
annotations:
|
||||
|
||||
@@ -30,6 +30,6 @@ spec:
|
||||
component: backend
|
||||
ports:
|
||||
- name: backend
|
||||
port: 7000
|
||||
port: 7007
|
||||
protocol: TCP
|
||||
targetPort: backend
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
{
|
||||
"baseUrl": "http://localhost:7000",
|
||||
"baseUrl": "http://localhost:7007",
|
||||
"integrationFolder": "./src/integration",
|
||||
"supportFile": "./src/support",
|
||||
"fixturesFolder": "./src/fixtures",
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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: 278 KiB |
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
```
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
```
|
||||
|
||||
|
||||
|
||||
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.
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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!
|
||||
|
||||
+1
-1
@@ -2,5 +2,5 @@
|
||||
"packages": ["packages/*", "plugins/*"],
|
||||
"npmClient": "yarn",
|
||||
"useWorkspaces": true,
|
||||
"version": "0.1.0"
|
||||
"version": "0.0.0"
|
||||
}
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: Starting Phase 2: The Service Catalog
|
||||
title: 'Starting Phase 2: The Service Catalog'
|
||||
author: Stefan Ålund, Spotify
|
||||
authorURL: http://twitter.com/stalund
|
||||
authorImageURL: https://pbs.twimg.com/profile_images/121166861/6919c047c0d0edaace78c3009b28e917-user-full-200-130.generated_400x400.jpg
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: Announcing TechDocs: Spotify’s docs-like-code plugin for Backstage
|
||||
title: 'Announcing TechDocs: Spotify’s docs-like-code plugin for Backstage'
|
||||
author: Gary Niemen, Spotify
|
||||
authorURL: https://github.com/garyniemen
|
||||
---
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user