Merge remote-tracking branch 'origin/master' into mob/scaffolder-frontend
This commit is contained in:
Johan Haals
@@ -24,12 +24,18 @@ Backstage ecosystem.
|
||||
|
||||
## Project roadmap
|
||||
|
||||
| Version | Description |
|
||||
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Backstage Search V.0 ✅ | Search Frontend letting you search through the entities of the software catalog. [See V.0 Use Cases.](#backstage-search-v0) |
|
||||
| Backstage Search V.1 ⌛ | Basic “out-of-the-box” in-memory indexing process of entities, and their metadata, registered to the Software Catalog. [See V.1 Use Cases.](#backstage-search-v1) |
|
||||
| Backstage Search V.2 ⌛ | Search Backend responsible for the indexing process of entities, and their metadata, registered to the Software Catalog. [See V.2 Use Cases.](#backstage-search-v2) |
|
||||
| Backstage Search V.3 ⌛ | Standardized Search API lets you index other plugins data to the search engine of choice. [See V.3 Use Cases.](#backstage-search-v3) |
|
||||
| Version | Description |
|
||||
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| Backstage Search v0 ✅ | Search Frontend letting you search through the entities of the software catalog. [See v0 Use Cases.](#backstage-search-v0) |
|
||||
| [Backstage Search V0.5 ⌛][v0.5] | Foundations for the architecture. |
|
||||
| [Backstage Search v1 ⌛][v1] | Basic “out-of-the-box” in-memory indexing process of entities, and their metadata, registered to the Software Catalog. [See v1 Use Cases.](#backstage-search-v1) |
|
||||
| [Backstage Search v2 ⌛][v2] | Search Backend responsible for the indexing process of entities, and their metadata, registered to the Software Catalog. [See v2 Use Cases.](#backstage-search-v2) |
|
||||
| [Backstage Search v3 ⌛][v3] | Standardized Search API lets you index other plugins data to the search engine of choice. [See v3 Use Cases.](#backstage-search-v3) |
|
||||
|
||||
[v0.5]: https://github.com/backstage/backstage/milestone/25
|
||||
[v1]: https://github.com/backstage/backstage/milestone/26
|
||||
[v2]: https://github.com/backstage/backstage/milestone/27
|
||||
[v3]: https://github.com/backstage/backstage/milestone/28
|
||||
|
||||
## Use Cases
|
||||
|
||||
|
||||
@@ -6,9 +6,9 @@ description: Documentation on Search Architecture
|
||||
|
||||
# Search Architecture
|
||||
|
||||
> _This is a proposed architecture which has not been implemented yet. We are
|
||||
> still looking for feedback to improve the architecture to fit your use-case,
|
||||
> see [this open issue](https://github.com/backstage/backstage/issues/4078)._
|
||||
> _This is a proposed architecture which has not been implemented yet. Find our
|
||||
> milestones to follow our progress on the
|
||||
> [Search Roadmap](./README.md#project-roadmap)._
|
||||
|
||||
Below you can explore the Search Architecture. Our aim with this architecture is
|
||||
to support a wide variety of search engines, while providing a simple developer
|
||||
@@ -20,7 +20,10 @@ Backstage end-users.
|
||||
At a base-level, we want to support the following:
|
||||
|
||||
- We aim to enable the capability to search across the entire Backstage
|
||||
ecosystem by decoupling search from content management.
|
||||
ecosystem including, but not limited to, entities in the software catalog.
|
||||
Searchable content won't be required to relate directly to the software
|
||||
catalog, but by convention, we may encourage loose relationships using
|
||||
well-known field names or attributes.
|
||||
- We aim to enable the capability to deploy Backstage using any search engine,
|
||||
by providing an integration and translation layer between the core search
|
||||
plugin and search engine specific logic that can be extended for different
|
||||
@@ -29,11 +32,17 @@ At a base-level, we want to support the following:
|
||||
|
||||
More advanced use-cases we hope to support with this architecture include:
|
||||
|
||||
- It should be easy for any plugin to expose new content to search. (e.g. entity
|
||||
metadata, documentation from TechDocs)
|
||||
- It should be easy for any plugin to append relevant metadata to existing
|
||||
- It should be possible for any plugin to expose new content to search. (e.g.
|
||||
entity metadata, documentation from TechDocs)
|
||||
- It should be possible for any plugin to append relevant metadata to existing
|
||||
content in search. (e.g. location (path) for TechDocs page)
|
||||
- It should be easy to refine search queries (e.g. ranking, scoring, etc.)
|
||||
- It should be easy to customize the search UI
|
||||
- It should be easy to add search functionality to any Backstage plugin or
|
||||
- It should be possible to refine search queries (e.g. ranking, scoring, etc.)
|
||||
- It should be possible to customize the search UI
|
||||
- It should be possible to add search functionality to any Backstage plugin or
|
||||
deployment
|
||||
|
||||
Architecture non-goals:
|
||||
|
||||
- At this time, we do not intend to directly support event-driven or incremental
|
||||
index management. Instead, we'll be focused on scheduled, bulk index
|
||||
management.
|
||||
|
||||
@@ -27,11 +27,15 @@ REPOSITORY_URL='https://github.com/org/repo'
|
||||
git clone $REPOSITORY_URL
|
||||
cd repo
|
||||
|
||||
# Install @techdocs/cli, mkdocs and mkdocs plugins
|
||||
npm install -g @techdocs/cli
|
||||
pip install mkdocs-techdocs-core==0.*
|
||||
|
||||
# Generate
|
||||
npx @techdocs/cli generate
|
||||
techdocs-cli generate --no-docker
|
||||
|
||||
# Publish
|
||||
npx @techdocs/cli publish --publisher-type awsS3 --storage-name <bucket/container> --entity <Namespace/Kind/Name>
|
||||
techdocs-cli publish --publisher-type awsS3 --storage-name <bucket/container> --entity <Namespace/Kind/Name>
|
||||
```
|
||||
|
||||
That's it!
|
||||
@@ -40,14 +44,16 @@ Take a look at
|
||||
[`techdocs-cli` README](https://github.com/backstage/techdocs-cli) for the
|
||||
complete command reference, details, and options.
|
||||
|
||||
## 1. Setup a workflow
|
||||
## Steps
|
||||
|
||||
### 1. Setup a workflow
|
||||
|
||||
The TechDocs workflow should trigger on CI when any changes are made in the
|
||||
repository containing the documentation files. You can be specific and configure
|
||||
the workflow to be triggered only when files inside the `docs/` directory or
|
||||
`mkdocs.yml` are changed.
|
||||
|
||||
## 2. Prepare step
|
||||
### 2. Prepare step
|
||||
|
||||
The first step on the CI is to clone your documentation source repository in a
|
||||
working directory. This is almost always the first step in most CI workflows.
|
||||
@@ -62,7 +68,7 @@ step.
|
||||
|
||||
Eventually we are trying to do a `git clone <https://path/to/docs-repository/>`.
|
||||
|
||||
## 3. Generate step
|
||||
### 3. Generate step
|
||||
|
||||
Install [`npx`](https://www.npmjs.com/package/npx) to use it for running
|
||||
`techdocs-cli`. Or you can install using `npm install -g @techdocs/cli`.
|
||||
@@ -78,7 +84,7 @@ npx @techdocs/cli generate --no-docker --source-dir PATH_TO_REPO --output-dir ./
|
||||
`PATH_TO_REPO` should be the location in the file path where the prepare step
|
||||
above clones the repository.
|
||||
|
||||
## 4. Publish step
|
||||
### 4. Publish step
|
||||
|
||||
Depending on your cloud storage provider (AWS, Google Cloud, or Azure), set the
|
||||
necessary authentication environment variables.
|
||||
@@ -96,3 +102,68 @@ npx @techdocs/cli publish --publisher-type <awsS3|googleGcs> --storage-name <buc
|
||||
|
||||
The updated TechDocs site built in this workflow is now ready to be served by
|
||||
the TechDocs plugin in your Backstage app.
|
||||
|
||||
## Example: GitHub Actions CI and AWS S3
|
||||
|
||||
Here is an example workflow using GitHub Actions CI and AWS S3 storage. You can
|
||||
use any CI and any other
|
||||
[TechDocs supported cloud storage providers](README.md#platforms-supported).
|
||||
|
||||
Add a `.github/workflows/techdocs.yml` file in your
|
||||
[Software Template(s)](../software-templates/index.md) like this -
|
||||
|
||||
```yaml
|
||||
name: Publish TechDocs Site
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
# You can even set it to run only when TechDocs related files are updated.
|
||||
# paths:
|
||||
# - "docs/**"
|
||||
# - "mkdocs.yml"
|
||||
|
||||
jobs:
|
||||
publish-techdocs-site:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
# The following secrets are required in your CI environment for publishing files to AWS S3.
|
||||
# e.g. You can use GitHub Organization secrets to set them for all existing and new repositories.
|
||||
env:
|
||||
TECHDOCS_S3_BUCKET_NAME: ${{ secrets.TECHDOCS_S3_BUCKET_NAME }}
|
||||
AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
|
||||
AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
|
||||
AWS_REGION: ${{ secrets.AWS_REGION }}
|
||||
ENTITY_NAMESPACE: 'default'
|
||||
ENTITY_KIND: 'Component'
|
||||
ENTITY_NAME: 'my-doc-entity'
|
||||
# In a Software template, Scaffolder will replace {{cookiecutter.component_id | jsonify}}
|
||||
# with the correct entity name. This is same as metadata.name in the entity's catalog-info.yaml
|
||||
# ENTITY_NAME: '{{ cookiecutter.component_id | jsonify }}'
|
||||
|
||||
steps:
|
||||
- name: Checkout code
|
||||
uses: actions/checkout@v2
|
||||
|
||||
- uses: actions/setup-node@v2
|
||||
- uses: actions/setup-python@v2
|
||||
|
||||
- name: Install techdocs-cli
|
||||
run: sudo npm install -g @techdocs/cli
|
||||
|
||||
- name: Install mkdocs and mkdocs plugins
|
||||
run: python -m pip install mkdocs-techdocs-core==0.*
|
||||
|
||||
- name: Generate docs site
|
||||
run: techdocs-cli generate --no-docker --verbose
|
||||
|
||||
- name: Publish docs site
|
||||
run:
|
||||
techdocs-cli publish --publisher-type awsS3 --storage-name
|
||||
$TECHDOCS_S3_BUCKET_NAME --entity
|
||||
$ENTITY_NAMESPACE/$ENTITY_KIND/$ENTITY_NAME
|
||||
```
|
||||
|
||||
When the new repository is scaffolded or new documentation updates are
|
||||
committed, the GitHub Action workflow will publish the TechDocs site, which can
|
||||
be viewed in your Backstage app.
|
||||
|
||||
@@ -157,15 +157,17 @@ techdocs:
|
||||
builder: 'local'
|
||||
```
|
||||
|
||||
Set `techdocs.builder` to `'local'` if you want your TechDocs Backend to be
|
||||
responsible for generating documentation sites. If set to `'external'`,
|
||||
Backstage will assume that the sites are being generated on each entity's CI/CD
|
||||
pipeline, and are being stored in a storage somewhere.
|
||||
Note that we recommend generating docs on CI/CD instead. Read more in the
|
||||
"Basic" and "Recommended" sections of the
|
||||
[TechDocs Architecture](architecture.md). But if you want to get started quickly
|
||||
set `techdocs.builder` to `'local'` so that TechDocs Backend is responsible for
|
||||
generating documentation sites. If set to `'external'`, Backstage will assume
|
||||
that the sites are being generated on each entity's CI/CD pipeline, and are
|
||||
being stored in a storage somewhere.
|
||||
|
||||
When `techdocs.builder` is set to `'external'`, TechDocs becomes more or less a
|
||||
read-only experience where it serves static files from a storage containing all
|
||||
the generated documentation. Read more in the "Basic" and "Recommended" sections
|
||||
of the [TechDocs Architecture](architecture.md).
|
||||
the generated documentation.
|
||||
|
||||
### Choosing storage (publisher)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user