diff --git a/.github/workflows/e2e-win.yml b/.github/workflows/e2e-win.yml index 37cb13ffbe..5ebf67bc9a 100644 --- a/.github/workflows/e2e-win.yml +++ b/.github/workflows/e2e-win.yml @@ -33,19 +33,11 @@ jobs: with: node-version: ${{ matrix.node-version }} registry-url: https://registry.npmjs.org/ # Needed for auth - - name: cache all node_modules - id: cache-modules - uses: actions/cache@v2 - with: - path: '**/node_modules' - key: ${{ runner.os }}-node_modules-${{ hashFiles('yarn.lock', '**/package.json') }} - name: find location of global yarn cache id: yarn-cache - if: steps.cache-modules.outputs.cache-hit != 'true' run: echo "::set-output name=dir::$(yarn cache dir)" - name: cache global yarn cache uses: actions/cache@v2 - if: steps.cache-modules.outputs.cache-hit != 'true' with: path: ${{ steps.yarn-cache.outputs.dir }} key: ${{ runner.os }}-yarn-${{ hashFiles('yarn.lock') }} diff --git a/.github/workflows/master-win.yml b/.github/workflows/master-win.yml index b5a042a236..296a7511bc 100644 --- a/.github/workflows/master-win.yml +++ b/.github/workflows/master-win.yml @@ -25,19 +25,11 @@ jobs: with: node-version: ${{ matrix.node-version }} registry-url: https://registry.npmjs.org/ # Needed for auth - - name: cache all node_modules - id: cache-modules - uses: actions/cache@v2 - with: - path: '**/node_modules' - key: ${{ runner.os }}-node_modules-${{ hashFiles('yarn.lock', '**/package.json') }} - name: find location of global yarn cache id: yarn-cache - if: steps.cache-modules.outputs.cache-hit != 'true' run: echo "::set-output name=dir::$(yarn cache dir)" - name: cache global yarn cache uses: actions/cache@v2 - if: steps.cache-modules.outputs.cache-hit != 'true' with: path: ${{ steps.yarn-cache.outputs.dir }} key: ${{ runner.os }}-yarn-${{ hashFiles('yarn.lock') }} diff --git a/app-config.yaml b/app-config.yaml index 6202d48560..5347fbe617 100644 --- a/app-config.yaml +++ b/app-config.yaml @@ -14,21 +14,15 @@ backend: client: sqlite3 connection: ':memory:' +# See README.md in the proxy-backend plugin for information on the configuration format proxy: - '/circleci/api': - target: 'https://circleci.com/api/v1.1' - changeOrigin: true - pathRewrite: - '^/proxy/circleci/api/': '/' + '/circleci/api': https://circleci.com/api/v1.1 '/jenkins/api': - target: 'http://localhost:8080' - changeOrigin: true + target: http://localhost:8080 headers: Authorization: $secret: env: JENKINS_BASIC_AUTH_HEADER - pathRewrite: - '^/proxy/jenkins/api/': '/' organization: name: Spotify @@ -51,6 +45,26 @@ newrelic: key: NEW_RELIC_REST_API_KEY catalog: + processors: + githubApi: + privateToken: + $secret: + env: GITHUB_PRIVATE_TOKEN + bitbucketApi: + username: + $secret: + env: BITBUCKET_USERNAME + appPassword: + $secret: + env: BITBUCKET_APP_PASSWORD + gitlabApi: + privateToken: + $secret: + env: GITLAB_PRIVATE_TOKEN + azureApi: + privateToken: + $secret: + env: AZURE_PRIVATE_TOKEN exampleEntityLocations: github: - https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/artist-lookup-component.yaml @@ -61,6 +75,11 @@ catalog: - https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/playback-lib-component.yaml - https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/www-artist-component.yaml - https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/shuffle-api-component.yaml + - https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/sample-templates/react-ssr-template/template.yaml + - https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/sample-templates/springboot-grpc-template/template.yaml + - https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/sample-templates/create-react-app/template.yaml + - https://github.com/spotify/cookiecutter-golang/blob/master/template.yaml + - https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/sample-templates/docs-template/template.yaml auth: providers: @@ -136,8 +155,6 @@ auth: env: AUTH_AUTH0_DOMAIN microsoft: development: - appOrigin: 'http://localhost:3000/' - secure: false clientId: $secret: env: AUTH_MICROSOFT_CLIENT_ID diff --git a/docs/FAQ.md b/docs/FAQ.md index d230e682a4..4b5df3ace0 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -3,7 +3,7 @@ id: FAQ title: FAQ --- -## Product FAQ: +## Product FAQ ### Can we call Backstage something different? So that it fits our company better? @@ -67,7 +67,7 @@ valuable as you grow. Yes! The Backstage UI is built using Material-UI. With the theming capabilities of Material-UI, you are able to adapt the interface to your brand guidelines. -## Technical FAQ: +## Technical FAQ ### Why Material-UI? diff --git a/docs/README.md b/docs/README.md index 55e178b691..c63a12b589 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,105 +1,3 @@ -# Documentation structure +# Documentation -**Note!** This documentation structure is very much work in progress. If (when, -really 😆) you find broken links or missing content, please create an issue or, -better yet, a pull request. - -# Plugins - -- Overview - - [What is Backstage?](overview/what-is-backstage.md) - - [Backstage architecture](overview/architecture-overview.md) - - [Architecture and terminology](overview/architecture-terminology.md) - - [Roadmap](overview/roadmap.md) - - [Vision](overview/vision.md) - - [Strategies for adopting](overview/adopting.md) -- Getting started - - [Running Backstage locally](getting-started/index.md) - - [Installation](getting-started/installation.md) - - [Local development](getting-started/development-environment.md) - - [Demo deployment](https://backstage-demo.roadie.io) - - Production deployments - - [Create an App](getting-started/create-an-app.md) - - App configuration - - [Configuring App with plugins](getting-started/configure-app-with-plugins.md) - - [Customize the look-and-feel of your App](getting-started/app-custom-theme.md) - - Deployment scenarios - - [Kubernetes](getting-started/deployment-k8s.md) - - [Other](getting-started/deployment-other.md) -- Features - - Software Catalog - - [Overview](features/software-catalog/index.md) - - [System model](features/software-catalog/system-model.md) - - [YAML File Format](features/software-catalog/descriptor-format.md) - - [Extending the model](features/software-catalog/extending-the-model.md) - - [External integrations](features/software-catalog/external-integrations.md) - - [API](features/software-catalog/api.md) - - Software creation templates - - [Overview](features/software-templates/index.md) - - [Adding templates](features/software-templates/adding-templates.md) - - Extending the Scaffolder: - - [Overview](features/software-templates/extending/index.md) - - [Create your own Templater](features/software-templates/extending/create-your-own-templater.md) - - [Create your own Publisher](features/software-templates/extending/create-your-own-publisher.md) - - [Create your own Preparer](features/software-templates/extending/create-your-own-preparer.md) - - Docs-like-code - - [Overview](features/techdocs/README.md) - - [Getting Started](features/techdocs/getting-started.md) - - [Concepts](features/techdocs/concepts.md) - - [Creating and Publishing Documentation](features/techdocs/creating-and-publishing.md) - - [FAQ](features/techdocs/FAQ.md) -- Plugins - - [Overview](plugins/index.md) - - [Existing plugins](plugins/existing-plugins.md) - - [Creating a new plugin](plugins/create-a-plugin.md) - - [Developing a plugin](plugins/plugin-development.md) - - [Structure of a plugin](plugins/structure-of-a-plugin.md) - - Backends and APIs - - [Proxying](plugins/proxying.md) - - [Backstage backend plugin](plugins/backend-plugin.md) - - [Call existing API](plugins/call-existing-api.md) - - Testing - - [Overview](plugins/testing.md) - - Publishing - - [Open source and NPM](plugins/publishing.md) - - [Private/internal (non-open source)](plugins/publish-private.md) -- Configuration - - [Overview](conf/index.md) - - [Reading Configuration](conf/reading.md) - - [Writing Configuration](conf/writing.md) - - [Defining Configuration](conf/defining.md) -- Authentication and identity - - [Overview](auth/index.md) - - [Add auth provider](auth/add-auth-provider.md) - - [Auth backend](auth/auth-backend.md) - - [OAuth](auth/oauth.md) - - [Glossary](auth/glossary.md) -- Designing for Backstage - - [Backstage Design Language System (DLS)](dls/design.md) - - [Storybook -- reusable UI components](http://backstage.io/storybook) - - [Contributing to Storybook](dls/contributing-to-storybook.md) - - [Figma resources](dls/figma.md) -- API references - - TypeScript API - - [Utility APIs](api/utility-apis.md) - - [Utility API References](reference/utility-apis/README.md) - - [createPlugin](reference/createPlugin.md) - - [createPlugin-feature-flags](reference/createPlugin-feature-flags.md) - - [createPlugin-router](reference/createPlugin-router.md) - - Backend APIs - - [Backend](api/backend.md) -- Tutorials - - [Overview](tutorials/index.md) -- Architecture Decision Records (ADRs) - - [Overview](architecture-decisions/index.md) - - [ADR001 - Architecture Decision Record (ADR) log](architecture-decisions/adr001-add-adr-log.md) - - [ADR002 - Default Software Catalog File Format](architecture-decisions/adr002-default-catalog-file-format.md) - - [ADR003 - Avoid Default Exports and Prefer Named Exports](architecture-decisions/adr003-avoid-default-exports.md) - - [ADR004 - Module Export Structure](architecture-decisions/adr004-module-export-structure.md) - - [ADR005 - Catalog Core Entities](architecture-decisions/adr005-catalog-core-entities.md) - - [ADR006 - Avoid React.FC and React.SFC](architecture-decisions/adr006-avoid-react-fc.md) - - [ADR007 - Use MSW for Mocking Network Requests](architecture-decisions/adr007-use-msw-to-mock-service-requests.md) - - [ADR008 - Default Catalog File Name](architecture-decisions/adr008-default-catalog-file-name.md) -- [Contribute](../CONTRIBUTING.md) -- [Support](overview/support.md) -- [FAQ](FAQ.md) +The Backstage documentation is available at https://backstage.io/docs diff --git a/docs/architecture-decisions/index.md b/docs/architecture-decisions/index.md index b02e8deabb..91d2c668d7 100644 --- a/docs/architecture-decisions/index.md +++ b/docs/architecture-decisions/index.md @@ -4,8 +4,6 @@ title: Architecture Decision Records (ADR) sidebar_label: Overview --- -# - The substantial architecture decisions made in the Backstage project lives here. For more information about ADRs, when to write them, and why, please see [this blog post](https://engineering.atspotify.com/2020/04/14/when-should-i-write-an-architecture-decision-record/). @@ -25,7 +23,10 @@ Records should be stored under the `architecture-decisions` directory. - Submit a pull request - Address and integrate feedback from the community - Eventually, assign a number -- Add the full path of the ADR to the [`mkdocs.yml`](/mkdocs.yml) +- Add the path of the ADR to the microsite sidebar in + [`sidebars.json`](https://github.com/spotify/backstage/blob/master/microsite/sidebars.json) +- Add the path of the ADR to the + [`mkdocs.yml`](https://github.com/spotify/backstage/blob/master/mkdocs.yml) - Merge the pull request ## Superseding an ADR diff --git a/docs/getting-started/create-app_output.png b/docs/assets/getting-started/create-app_output.png similarity index 100% rename from docs/getting-started/create-app_output.png rename to docs/assets/getting-started/create-app_output.png diff --git a/docs/getting-started/create-plugin_output.png b/docs/assets/getting-started/create-plugin_output.png similarity index 100% rename from docs/getting-started/create-plugin_output.png rename to docs/assets/getting-started/create-plugin_output.png diff --git a/docs/features/software-catalog/bsc-edit.png b/docs/assets/software-catalog/bsc-edit.png similarity index 100% rename from docs/features/software-catalog/bsc-edit.png rename to docs/assets/software-catalog/bsc-edit.png diff --git a/docs/features/software-catalog/bsc-extend.png b/docs/assets/software-catalog/bsc-extend.png similarity index 100% rename from docs/features/software-catalog/bsc-extend.png rename to docs/assets/software-catalog/bsc-extend.png diff --git a/docs/features/software-catalog/bsc-register-1.png b/docs/assets/software-catalog/bsc-register-1.png similarity index 100% rename from docs/features/software-catalog/bsc-register-1.png rename to docs/assets/software-catalog/bsc-register-1.png diff --git a/docs/features/software-catalog/bsc-register-2.png b/docs/assets/software-catalog/bsc-register-2.png similarity index 100% rename from docs/features/software-catalog/bsc-register-2.png rename to docs/assets/software-catalog/bsc-register-2.png diff --git a/docs/features/software-catalog/bsc-search.png b/docs/assets/software-catalog/bsc-search.png similarity index 100% rename from docs/features/software-catalog/bsc-search.png rename to docs/assets/software-catalog/bsc-search.png diff --git a/docs/features/software-catalog/bsc-starred.png b/docs/assets/software-catalog/bsc-starred.png similarity index 100% rename from docs/features/software-catalog/bsc-starred.png rename to docs/assets/software-catalog/bsc-starred.png diff --git a/docs/features/software-catalog/software-model-core-entities.png b/docs/assets/software-catalog/software-model-core-entities.png similarity index 100% rename from docs/features/software-catalog/software-model-core-entities.png rename to docs/assets/software-catalog/software-model-core-entities.png diff --git a/docs/assets/techdocs/techdocs_big_picture.png b/docs/assets/techdocs/techdocs_big_picture.png new file mode 100644 index 0000000000..ffe437180f Binary files /dev/null and b/docs/assets/techdocs/techdocs_big_picture.png differ diff --git a/docs/auth/auth-backend-classes.md b/docs/auth/auth-backend-classes.md index 42ee48c5e0..9034a3d054 100644 --- a/docs/auth/auth-backend-classes.md +++ b/docs/auth/auth-backend-classes.md @@ -1,4 +1,7 @@ -# Authentication Backend Classes Layout and Description +--- +id: auth-backend-classes +title: Auth backend classes +--- ## How Does Authentication Work? diff --git a/docs/auth/oauth.md b/docs/auth/oauth.md index 6e6dc4da80..b7013a310d 100644 --- a/docs/auth/oauth.md +++ b/docs/auth/oauth.md @@ -104,6 +104,8 @@ request an access token. The following diagram visualizes the flow described in the previous section. +![](oauth-popup-flow.svg) + - -![](oauth-popup-flow.svg) diff --git a/docs/features/software-catalog/extending-the-model.md b/docs/features/software-catalog/extending-the-model.md index ce5ea03b26..8b621f2e44 100644 --- a/docs/features/software-catalog/extending-the-model.md +++ b/docs/features/software-catalog/extending-the-model.md @@ -12,7 +12,7 @@ Backstage natively supports tracking of the following component - Documentation - Other -![](bsc-extend.png) +![](../../assets/software-catalog/bsc-extend.png) Since these types are likely not the only kind of software you will want to track in Backstage, it is possible to @@ -31,9 +31,10 @@ catalog. It might be tempting to put software that doesn't fit into any of the existing types into Other. There are a few reasons why we advice against this; firstly, we have found that it is preferred to match the conceptual model that your -engineers have when describing your sofware. Secondly, Backstage helps your -engineers manage their software by integrating the infratrucure tooling through -plugins. Different plugins are used for managing different types of components. +engineers have when describing your software. Secondly, Backstage helps your +engineers manage their software by integrating the infrastructure tooling +through plugins. Different plugins are used for managing different types of +components. For example, the [Lighthouse plugin](https://github.com/spotify/backstage/tree/master/plugins/lighthouse) diff --git a/docs/features/software-catalog/index.md b/docs/features/software-catalog/index.md index fe107d1f59..db8c183390 100644 --- a/docs/features/software-catalog/index.md +++ b/docs/features/software-catalog/index.md @@ -1,6 +1,7 @@ --- id: software-catalog-overview title: Backstage Service Catalog (alpha) +sidebar_label: Backstage Service Catalog --- ## What is a Service Catalog? @@ -54,18 +55,18 @@ There are 3 ways to add components to the catalog: Users can register new components by going to `/create` and clicking the **REGISTER EXISTING COMPONENT** button: -![](bsc-register-1.png) +![](../../assets/software-catalog/bsc-register-1.png) Backstage expects the full URL to the YAML in your source control. Example: -``` +```bash https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/artist-lookup-component.yaml ``` _More examples can be found [here](https://github.com/spotify/backstage/tree/master/packages/catalog-model/examples)._ -![](bsc-register-2.png) +![](../../assets/software-catalog/bsc-register-2.png) It is important to note that any kind of software can be registered in Backstage. Even if the software is not maintained by your company (SaaS @@ -83,7 +84,7 @@ registered in the catalog. Teams owning the components are responsible for maintaining the metadata about them, and do so using their normal Git workflow. -![](bsc-edit.png) +![](../../assets/software-catalog/bsc-edit.png) Once the change has been merged, Backstage will automatically show the updated metadata in the service catalog after a short while. @@ -92,25 +93,25 @@ metadata in the service catalog after a short while. By default the service catalog shows components owned by the team of the logged in user. But you can also switch to _All_ to see all the components across your -companie's software ecosystem. Basic inline _search_ and _column filtering_ -makes it easy to browse a big set of components. +company's software ecosystem. Basic inline _search_ and _column filtering_ makes +it easy to browse a big set of components. -![](bsc-search.png) +![](../../assets/software-catalog/bsc-search.png) ## Starring components For easy and quick access to components you visit frequently, Backstage supports _starring_ of components: -![](bsc-starred.png) +![](../../assets/software-catalog/bsc-starred.png) ## Integrated tooling through plugins -The service catalog is a great way to organise the infrastructure tools you use +The service catalog is a great way to organize the infrastructure tools you use to manage the software. This is how Backstage creates one developer portal for all your tools. Rather than asking teams to jump between different -infrastructure UI’s (and incurring additional cognitive overhead each time they -make a context switch), most of these tools can be organised around the entities +infrastructure UIs (and incurring additional cognitive overhead each time they +make a context switch), most of these tools can be organized around the entities in the catalog. ![tools](https://backstage.io/blog/assets/20-05-20/tabs.png) diff --git a/docs/features/software-catalog/system-model.md b/docs/features/software-catalog/system-model.md index 435fe05b48..4436f60fc2 100644 --- a/docs/features/software-catalog/system-model.md +++ b/docs/features/software-catalog/system-model.md @@ -16,11 +16,13 @@ We model software in the Backstage catalogue using these three core entities (further explained below): - **Components** are individual pieces of software + - **APIs** are the boundaries between different components + - **Resources** are physical or virtual infrastructure needed to operate a component -![](system-model-core-entities.png) +![](../../assets/software-catalog/software-model-core-entities.png) ### Component @@ -29,22 +31,22 @@ backend service or data pipeline (list not exhaustive). A component can be tracked in source control, or use some existing open source or commercial software. -A component can implement APIs for other components to consume. In turn it -might depend on APIs implemented by other components, or resources that are -attached to it at runtime. +A component can implement APIs for other components to consume. In turn it might +depend on APIs implemented by other components, or resources that are attached +to it at runtime. ### API APIs form an important (maybe the most important) abstraction that allows large software ecosystems to scale. Thus, APIs are a first class citizen in the -Backstage model and the primary way to discover existing functionality in -the ecosystem. +Backstage model and the primary way to discover existing functionality in the +ecosystem. APIs are implemented by components and form boundaries between components. They -might be defined using an RPC IDL (eg Protobuf, GraphQL, ...), a data schema -(eg Avro, TFRecord, ...), or as code interfaces. In any case, APIs exposed by -components need to be in a known machine-readable format so we can -build further tooling and analysis on top. +might be defined using an RPC IDL (eg Protobuf, GraphQL, ...), a data schema (eg +Avro, TFRecord, ...), or as code interfaces. In any case, APIs exposed by +components need to be in a known machine-readable format so we can build further +tooling and analysis on top. APIs have a visibility: they are either public (making them available for any other component to consume), restricted (only available to a whitelisted set of @@ -62,12 +64,13 @@ footprint, and create tooling around them. ## Ecosystem Modeling -A large catalogue of components, APIs and resources can be highly granular -and hard to understand as a whole. It might thus be convenient to further -categorize these entities using the following (optional) concepts: -* **Systems** are a collection of entities that cooperate to perform some - function -* **Domains** relate entities and systems to part of the business +A large catalogue of components, APIs and resources can be highly granular and +hard to understand as a whole. It might thus be convenient to further categorize +these entities using the following (optional) concepts: + +- **Systems** are a collection of entities that cooperate to perform some + function +- **Domains** relate entities and systems to part of the business ### System @@ -82,15 +85,16 @@ exposes one or several public APIs. The main benefit of modelling a system is that it hides its resources and private APIs between the components for any consumers. This means that as the owner, you can evolve the implementation, in terms of components and resources, without your consumers being able to notice. -Typically, a system will consist of at most a handful of components (see -Domain for a grouping of systems). +Typically, a system will consist of at most a handful of components (see Domain +for a grouping of systems). -For example, a playlist management system might encapsulate a backend service -to update playlists, a backend service to query them, and a database to store -them. It could expose an RPC API, a daily snapshots dataset, and an event -stream of playlist updates. +For example, a playlist management system might encapsulate a backend service to +update playlists, a backend service to query them, and a database to store them. +It could expose an RPC API, a daily snapshots dataset, and an event stream of +playlist updates. ### Domain + While systems are the basic level of encapsulation for related entities, it is often useful to group a collection of systems that share terminology, domain models, metrics, KPIs, business purpose, or documentation, i.e. they form a diff --git a/docs/features/software-templates/adding-templates.md b/docs/features/software-templates/adding-templates.md index 67e9c23605..67467bd98e 100644 --- a/docs/features/software-templates/adding-templates.md +++ b/docs/features/software-templates/adding-templates.md @@ -58,7 +58,7 @@ Currently the catalog supports loading definitions from GitHub + Local Files. To load from other places, not only will there need to be another preparer, but the support to load the location will also need to be added to the Catalog. -For loading from a file the following command should work when the backend is +For loading from a file, the following command should work when the backend is running: ```sh @@ -69,7 +69,7 @@ curl \ --data-raw "{\"type\": \"file\", \"target\": \"${YOUR PATH HERE}/template.yaml\"}" ``` -If loading from a git location, you can run the following +If loading from a Git location, you can run the following ```sh curl \ @@ -83,7 +83,7 @@ This should then have added the catalog, and also should now be listed under the create page at http://localhost:3000/create. Alternatively, if you want to get setup with some mock templates that are -already provided for you, you can run the following to load those templates: +already provided, run the following to load those templates: ``` yarn lerna run mock-data diff --git a/docs/features/software-templates/extending/create-your-own-publisher.md b/docs/features/software-templates/extending/create-your-own-publisher.md index 51869dc3ad..391f6f0658 100644 --- a/docs/features/software-templates/extending/create-your-own-publisher.md +++ b/docs/features/software-templates/extending/create-your-own-publisher.md @@ -7,8 +7,8 @@ Publishers are responsible for pushing and storing the templated skeleton after the values have been templated by the `Templater`. See [Create your own templater](./create-your-own-templater.md) for more info. -They recieve a directory or location where the templater has sucessfully run on, -and is now ready to store somewhere. They also get given some other options +They receive a directory or location where the templater has sucessfully run +and is now ready to store somewhere. They also are given some other options which are sent from the frontend, such as the `storePath` which is a string of where the frontend thinks we should save this templated folder. @@ -17,7 +17,7 @@ Currently we provide the following `publishers`: - `github` This publisher is passed through to the `createRouter` function of the -`@spotify/plugin-scaffolder-backend`. Currently only one publisher is supported, +`@spotify/plugin-scaffolder-backend`. Currently, only one publisher is supported, but PR's are always welcome. An full example backend can be found diff --git a/docs/features/software-templates/extending/create-your-own-templater.md b/docs/features/software-templates/extending/create-your-own-templater.md index a39f87924b..9dee66af06 100644 --- a/docs/features/software-templates/extending/create-your-own-templater.md +++ b/docs/features/software-templates/extending/create-your-own-templater.md @@ -8,14 +8,14 @@ returned by the preparers, and then executing the templating command on top of the file and returning the completed template path. This may or may not be the same directory as the input directory. -They also recieve additional values from the frontend, which can be used to +They also receive additional values from the frontend, which can be used to interpolate into the skeleton files. Currently we provide the following templaters: - `cookiecutter` -This templater is added the `TemplaterBuilder` and then passed into the +This templater is added to the `TemplaterBuilder` and then passed into the `createRouter` function of the `@spotify/plugin-scaffolder-backend` An full example backend can be found @@ -48,7 +48,7 @@ This `TemplaterKey` is used to select the correct templater from the `spec.templater` in the [Template Entity](../../software-catalog/descriptor-format.md#kind-template). -If you wish to add a new templater you'll need to register it with the +If you wish to add a new templater, you'll need to register it with the `TemplaterBuilder`. ### Creating your own Templater to add to the `TemplaterBuilder` @@ -83,10 +83,10 @@ follows: - `dockerClient` - a [dockerode](https://github.com/apocas/dockerode) client to be able to run docker containers. -_note_ currently the templaters that we provide are basically docker action +_note_ Currently the templaters that we provide are basically Docker action containers that are run on top of the skeleton folder. This keeps dependencies to a minimal for running backstage scaffolder, but you don't /have/ to use -docker. You could create your own templater that spins up an EC2 instance and +Docker. You could create your own templater that spins up an EC2 instance and downloads the folder and does everything using an AMI if you want. It's entirely up to you! @@ -138,7 +138,7 @@ spec: description: Description of the component ``` -You see that the `spec.templater` is set as `handlebars`, you'll need to +You see that the `spec.templater` is set as `handlebars`, so you'll need to register this with the `TemplaterBuilder` like so: ```ts diff --git a/docs/features/software-templates/extending/index.md b/docs/features/software-templates/extending/index.md index 21d8befda1..02d27a5725 100644 --- a/docs/features/software-templates/extending/index.md +++ b/docs/features/software-templates/extending/index.md @@ -5,11 +5,11 @@ title: Extending the Scaffolder Welcome. Take a seat. You're at the Scaffolder Documentation. -So - You wanna create stuff inside your company from some prebaked templates? +So, you want to create stuff inside your company from some prebaked templates? You're at the right place. -This guide is gonna take you through how the Scaffolder in Backstage works. -We'll dive into some jargon and run through whats going on in the backend to be +This guide is going to take you through how the Scaffolder in Backstage works. +We'll dive into some jargon and run through what's going on in the backend to be able to create these templates. There's also more guides that you might find useful at the bottom of this document. At it's core, theres 3 simple stages. @@ -25,9 +25,9 @@ scaffolder that you will need to know: 3. Publish Each of these steps can be configured for your own use case, but we provide some -sensible defaults too. +sensible defaults, too. -Lets dive a little deeper into these phases. +Let's dive a little deeper into these phases. ### Glossary and Jargon @@ -38,8 +38,8 @@ the router to pick the correct `Preparer` to run for the `Template` entity. **Templater** - The templater is responsible for actually running the chosen templater on top of the previously returned temporary directory from the -**Preprarer**. We advise making these docker containers as it can keep all -dependencies, for example Cookiecutter, self contained and not a dependency on +**Preprarer**. We advise making these Docker containers as it can keep all +dependencies--for example Cookiecutter--self contained and not a dependency on the host machine. **Publisher** - The publisher is responsible for taking the finished directory, @@ -50,11 +50,11 @@ passed through to the scaffolder backend. ### How it works -The main of the heavy lifting is done in the +Most of the heavy lifting is done in the [router.ts](https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/src/service/router.ts#L93) file in the `scaffolder-backend` plugin. -There are 2 routes defined in the router. `POST /v1/jobs` and +There are two routes defined in the router: `POST /v1/jobs` and `GET /v1/job/:jobId` To create a scaffolding job, a JSON object containing the @@ -78,7 +78,7 @@ additional templating values must be posted as the post body. The values should represent something that is valid with the `schema` part of the [Template Entity](../../software-catalog/descriptor-format.md#kind-template) -Once that has been posted, a job will be setup with different stages. And the +Once that has been posted, a job will be setup with different stages, and the job processor will complete each stage before moving onto the next stage, whilst collecting logs and mutating the running job. diff --git a/docs/features/software-templates/index.md b/docs/features/software-templates/index.md index 503fbb7a3d..1c67676b3e 100644 --- a/docs/features/software-templates/index.md +++ b/docs/features/software-templates/index.md @@ -4,8 +4,8 @@ title: Software Templates --- The Software Templates part of Backstage is a tool that can help you create -Components inside Backstage. It by default has the ability to load skeletons of -code, template in some variables and then publish the template to some location +Components inside Backstage. By default, it has the ability to load skeletons of +code, template in some variables, and then publish the template to some location like GitHub.