Merge pull request #28865 from backstage/sennyeya/guide-template
feat(docs): start preparing a golden path
This commit is contained in:
Aramis Sennyey
@@ -0,0 +1,38 @@
|
||||
<!-- THIS FILE IS NOT INTENDED TO BE DISPLAYED ON THE DOCSITE -->
|
||||
|
||||
# Glossary
|
||||
|
||||
- Page: A single `md` file.
|
||||
- Guide: A number of pages grouped under the same folder.
|
||||
|
||||
# Overall Writing Guidelines
|
||||
|
||||
The goal of these docs is to provide a comprehensive set of guides that technical champions and non-technical users can use to know what to expect on their Backstage adoption journey. This should include a host of resources for how to quantify impact of Backstage, how to present those finding to leadership, focusing on the right things for your company and tips and tricks for engaging with your developers.
|
||||
|
||||
When writing guide pages, keep it light! These should be instructional docs, and at the same time conversational and a joy to read. Guides should build on each other, when reading through a progression, the reader should feel more comfortable and confident with concepts as they pop up across progression levels. Guides should be standalone but can link across.
|
||||
|
||||
# Sections
|
||||
|
||||
Users should already have read through the summary section of the docs, "What is Backstage", "The Spotify story", etc.
|
||||
|
||||
## Getting started
|
||||
|
||||
We recommend you poke around the demo site to get a feel for what Backstage can provide. If you're technical, or working with someone technical, you can run through the steps in `golden-path/create-app` and `golden-path/deploying-backstage` to get something running for just your company.
|
||||
|
||||
## First round of stakeholder feedback
|
||||
|
||||
If you think Backstage is a good fit for your company, it's likely there are others that do or will think the same. You may have already identified them. For this initial round of feedback, share recommendations for what that group should look like, is there any required number of technical or non-technical members, do you need leadership involved at this point, etc.
|
||||
|
||||
For non-technical users, it's recommended to find a technical partner to help stand up a unique instance.
|
||||
|
||||
## Customizing your instance
|
||||
|
||||
At this point, we're assuming you already have an instance created through `golden-path/create-app` and `golden-path/deploying-backstage`. You should now start customizing it to your company's needs. We recommend you start small, write some catalog-info YAML files and start to build a personalized catalog.
|
||||
|
||||
## Second round of stakeholder feedback
|
||||
|
||||
## Getting leadership buy-in
|
||||
|
||||
## Plugin ownership and inner source mentality
|
||||
|
||||
## Driving to full catalog completion
|
||||
@@ -0,0 +1,62 @@
|
||||
<!-- THIS FILE IS NOT INTENDED TO BE DISPLAYED ON THE DOCSITE -->
|
||||
|
||||
# Glossary
|
||||
|
||||
- Page: A single `md` file.
|
||||
- Guide: A number of pages grouped under the same folder.
|
||||
|
||||
# Overall Writing Guidelines
|
||||
|
||||
The goal of these docs is to provide a comprehensive set of guides that any user can use to quickly get set up with a Backstage instance locally. Users should be assumed to have minimal knowledge of the Backstage ecosystem and may not even have the right tools installed (NodeJS, yarn, Docker, etc). This guide will be the first place we point them to, to get started and they should feel ready to take on the world after completing the entire golden path.
|
||||
|
||||
When writing guide pages, keep it light! These should be instructional docs, and at the same time conversational and a joy to read. Guides should build on each other, when reading through a progression, the reader should feel more comfortable and confident with concepts as they pop up across progression levels. Guides should be standalone but can link across.
|
||||
|
||||
# Sections
|
||||
|
||||
## Prerequisites
|
||||
|
||||
How to setup all of the dependencies. Installing NodeJS, versioning with nvm, installing brew and git. No stone to be left unturned, if it's a dependency of the project that gets used in the project output by the `create-app` script, it should be listed here with installation steps.
|
||||
|
||||
Some installation cases may be too complex to handle, like a bare bones VM or an air-gapped environment. This guide should generally focus on the primary developer environments, like Windows and Mac with an eye towards adding sections as demand grows for other technologies.
|
||||
|
||||
## `create-app`
|
||||
|
||||
How to run `create-app` and what the output means.
|
||||
|
||||
## Poking around your new application
|
||||
|
||||
How to login, how to navigate in the application.
|
||||
|
||||
### Common catalog use cases
|
||||
|
||||
### Common search use cases
|
||||
|
||||
### Common scaffolder use cases
|
||||
|
||||
## Development cycles
|
||||
|
||||
Hot reloading, webpack-dev-server, sqlite. What does the developer experience look like for local dev?
|
||||
|
||||
## Adding a frontend plugin
|
||||
|
||||
Walk through how to add a plugin, where it goes in the app, and what the additions in the lockfile mean.
|
||||
|
||||
## Adding a backend plugin
|
||||
|
||||
Walk through how to add a plugin to the backend, where it goes in the backend and what functionality is being added.
|
||||
|
||||
## Customizing the theme of your application
|
||||
|
||||
How to customize your application to match your organization's design system.
|
||||
|
||||
## Keeping Your Instance Up to Date
|
||||
|
||||
### New Backstage Releases
|
||||
|
||||
The main Backstage repository releases a new version every month with pre-release versions weekly. It is generally recommended to upgrade when the new release comes out every month.
|
||||
|
||||
Talk about the yarn plugin as an easier method here.
|
||||
|
||||
### Automatic Dependency Bumps
|
||||
|
||||
Backstage relies on a mountain of open source dependencies that make it as great as it is. As part of owning a deployed service, you also own the security posture - please make sure that you are observing best practices by bumping your dependencies through something like Dependabot or Renovate.
|
||||
@@ -0,0 +1,84 @@
|
||||
<!-- THIS FILE IS NOT INTENDED TO BE DISPLAYED ON THE DOCSITE -->
|
||||
|
||||
# Glossary
|
||||
|
||||
- Page: A single `md` file.
|
||||
- Guide: A number of pages grouped under the same folder.
|
||||
|
||||
# Overall Writing Guidelines
|
||||
|
||||
The goal of these docs is to provide a comprehensive set of guides that developers + admins can use to quickly get a Backstage instance into production and can refer to over time as their instance gain maturity.
|
||||
|
||||
A user that finishes all of these guides will feel comfortable running a Backstage deployment in production. That will include building the Docker image, monitoring the deployment, and keeping Backstage updated.
|
||||
|
||||
At the same time, not all users will finish the docs or they may come back to them as required. Individual guides should have strong "abstracts" (what will I learn by reading this guide), table of contents, and "next steps" (what do I need to do next) to guide users to read the most important pieces for their work.
|
||||
|
||||
When writing guide pages, keep it light! These should be instructional docs, and at the same time conversational and a joy to read. Guides should build on each other, when reading through a progression, the reader should feel more comfortable and confident with concepts as they pop up across progression levels. Guides should be standalone but can link across.
|
||||
|
||||
# Sections
|
||||
|
||||
Users are expected to already have created a Backstage application, but we have no expectations that they've customized anything.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
The user should already have created a Backstage application (`create-app`) and pushed their code to an origin in a source control management system (Github, Gitlab, etc). They should have a handle on how their company builds and deploys code.
|
||||
|
||||
## Deploying Backstage
|
||||
|
||||
Backstage should be deployed in the same way as other software at your company. Show common examples that may be useful when deploying Backstage for the first time, or for those without established deployment practices.
|
||||
|
||||
## Docker
|
||||
|
||||
### What's in the docker image?
|
||||
|
||||
Talk through the build process for the backend image and how we layer both the frontend and backend into the image.
|
||||
|
||||
### Running in CI
|
||||
|
||||
While you can run this build locally, we generally expect that you will run this as part of your CI build. Show the command that is needed and some context on what it does.
|
||||
|
||||
## Pre-deploy dependencies
|
||||
|
||||
### Database
|
||||
|
||||
SQLite is the default database for Backstage development, it's a fast in-memory database that can handle the day-to-day needs of developers. It doesn't work well for production use cases though - you generally want a dedicated database.
|
||||
|
||||
Use this section to walk through database options, talk through why Postgres is generally the best option and what config is needed to connect to common providers.
|
||||
|
||||
### Authentication
|
||||
|
||||
By default, Backstage lets users login through a guest user. While that's a good fit for a solid developer experience locally, it can open up security holes when it's deployed to production. For that reason, you should configure a different authentication provider. See the docs at `auth/*`. A solid choice is Github authentication - your target audience with a developer portal should already have access to Github.
|
||||
|
||||
## Deployment Guides
|
||||
|
||||
### ECS
|
||||
|
||||
### K8s
|
||||
|
||||
### Other
|
||||
|
||||
See `contrib/` section in the repo.
|
||||
|
||||
## Config-first Development
|
||||
|
||||
Making configuration the primary way to impact application behavior simplifies the deploy process and makes managing your Backstage instance much easier.
|
||||
|
||||
## Monitoring
|
||||
|
||||
### OpenTelemetry
|
||||
|
||||
Backstage provides a set of OpenTelemetry metrics by default. This guide will walk you through how to set those up, what to monitor for, and what good alarms look like.
|
||||
|
||||
### Frontend Analytics
|
||||
|
||||
Backstage also provides a frontend analytics API that can integrate with various vendors like Google Analytics for tracking user behavior on the frontend.
|
||||
|
||||
For frontend error reporting, you should consider integrating with something like CloudWatch RUM, Sentry or Cloudflare RUM.
|
||||
|
||||
## How to handle scale as usage grows
|
||||
|
||||
Talk about horizontal scaling, either by just increasing pod count or targeting specific expensive plugins and moving those to their own deployments.
|
||||
|
||||
### Separate frontend and backend
|
||||
|
||||
By default, the frontend is served from your deployment using the `@backstage/plugin-app-backend` plugin. If you need to split out the frontend and deploy it to a CDN, this section would show you how to do that.
|
||||
@@ -0,0 +1,131 @@
|
||||
<!-- THIS FILE IS NOT INTENDED TO BE DISPLAYED ON THE DOCSITE -->
|
||||
|
||||
# Glossary
|
||||
|
||||
- Page: A single `md` file.
|
||||
- Guide: A number of pages grouped under the same folder.
|
||||
|
||||
# Overall Writing Guidelines
|
||||
|
||||
The goal of these docs is to provide a comprehensive set of guides that developers + admins can use to quickly get up to speed with plugin development, and then refer to as they're developing their own plugins.
|
||||
|
||||
A user that finishes all of these guides will feel comfortable implementing plugins on their own. If additional assistance is required, they should be referred to other sources of information such as Discord, GitHub, source code, or documentation for further support. The user will also understand why/when to build their own plugins, inner-sourcing their developer portal and contributing internal plugins back to the open-source project.
|
||||
|
||||
At the same time, not all users will finish the docs or they may come back to them as required. Individual guides should have strong "abstracts" (what will I learn by reading this guide), table of contents, and "next steps" (what do I need to do next) to guide users to read the most important pieces for their work.
|
||||
|
||||
When writing guide pages, keep it light! These should be instructional docs, and at the same time conversational and a joy to read. Guides should build on each other, when reading through a progression, the reader should feel more comfortable and confident with concepts as they pop up across progression levels. Guides should be standalone, when finishing one level (for example 101), you should be able to immediately jump into the next (201) without additional research or background. Referencing previous progression levels is ok.
|
||||
|
||||
# Sections
|
||||
|
||||
## Why build plugins?
|
||||
|
||||
This section should answer definitely why you should build a new plugin. The Backstage framework is deeply empowered by plugins and plugins are core to the project's success. Users should walk away from reading this section with a conviction that plugins are the right path for new functionality.
|
||||
|
||||
## Sustainable plugin development
|
||||
|
||||
Plugins are not developed in a vacuum. Users should reach for them to solve specific business problems facing their developers, for example, you may be tasked to create
|
||||
|
||||
- a new vendor integration like PagerDuty,
|
||||
- a new plugin backend that talks to an internal service,
|
||||
- etc.
|
||||
|
||||
This section should contain learnings from successful Backstage deployments about how to engage with stakeholders, how/when to iterate on your plugin, and setting yourself up for future success.
|
||||
|
||||
## Creating your first plugin
|
||||
|
||||
This section should be extremely deliberate in showing readers every step of the way to create a plugin using Backstage's best practices. A reader that finishes this section should feel extremely comfortable creating new plugins and how to install and use plugins regardless of their experience with JS/TS and Backstage.
|
||||
|
||||
### Setting up your environment
|
||||
|
||||
This can point to the getting started section for setting everything up. Users should have NodeJS and yarn installed. They should also already have a scaffolded app.
|
||||
|
||||
### Scaffolding a new plugin
|
||||
|
||||
Talk through how to run the `backstage-cli create` command as well as what the output it creates is. This should touch on why we install this into `packages/backend`.
|
||||
|
||||
### Debugging
|
||||
|
||||
How to handle common errors like,
|
||||
|
||||
- Declaration error, `export default` missing
|
||||
- Startup error, `httpRouter` failed to start
|
||||
|
||||
## First steps with the new plugin
|
||||
|
||||
### Creating a todo plugin
|
||||
|
||||
We're going to be creating the backend for a todo list plugin. We want the user to be able to create todos for themselves and show the user their current list of todos.
|
||||
|
||||
To start, we will use an in-memory solution that naively writes to an array.
|
||||
|
||||
```ts
|
||||
const todos = [];
|
||||
todos.push({ id: 1, text: 'Write some code.' });
|
||||
console.log(todos);
|
||||
```
|
||||
|
||||
### HTTP API
|
||||
|
||||
We want our todo plugin to be externally accessible - in Backstage, the way we do that is through an HTTP API.
|
||||
|
||||
```ts
|
||||
app.post('/create', async (req, res) => {
|
||||
todos.push(req.body);
|
||||
});
|
||||
|
||||
app.get('/list', async (req, res) => {
|
||||
res.json(todos);
|
||||
});
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
Let's write a unit test using `supertest` to make sure that everything is working as expected.
|
||||
|
||||
After verifying everything, introduce the problem of persistence - the todos aren't saved across reloads.
|
||||
|
||||
### Persistence
|
||||
|
||||
Saving values to the database. Writing a migrations file. Plumbing through the database service.
|
||||
|
||||
## Integrations
|
||||
|
||||
Now that our plugin is ready for prime time, let's see how we can really leverage the rest of the Backstage ecosystem. Backstage provides a set of core features out of the box, namely, the Software Catalog, Search, Permissions, and Notifications.
|
||||
|
||||
### Catalog
|
||||
|
||||
We want to show our todos as separate Catalog entities. How can we make this happen?
|
||||
|
||||
### Search
|
||||
|
||||
We want to make our todos searchable.
|
||||
|
||||
### Permissions
|
||||
|
||||
We only want users to be able to find their own todos.
|
||||
|
||||
### Notifications
|
||||
|
||||
We want to set an alarm time for todos that sends a notification when the time is met.
|
||||
|
||||
## SCM Integrations
|
||||
|
||||
Our users love the new plugin, and now they want it to automatically fetch todos from their source code.
|
||||
|
||||
## Additional Resources and Further Reading
|
||||
|
||||
- **Real-world Implementations and Lessons**
|
||||
|
||||
- [Case studies and examples from the community](https://github.com/backstage/community#newsletters).
|
||||
- Best practices derived from mature implementations.
|
||||
- [Existing open-source community-maintained plugins](https://github.com/backstage/community-plugins).
|
||||
|
||||
- **Resource Compendium**
|
||||
|
||||
- [Backstage Glossary](https://backstage.io/docs/references/glossary) of key terms.
|
||||
- Recommended readings and tools for advanced developers.
|
||||
|
||||
- **Certification and Learning Pathways**
|
||||
- Pathways to deepen your understanding and expertise in plugin development for Backstage.
|
||||
|
||||
Stay tuned for detailed exploration and guidance in each of these modules. We're excited to accompany you on your plugin development journey!
|
||||
@@ -1,33 +0,0 @@
|
||||
<!-- THIS FILE IS NOT INTENDED TO BE DISPLAYED ON THE DOCSITE -->
|
||||
|
||||
# Intro to Plugin Development
|
||||
|
||||
## Writing Guidelines
|
||||
|
||||
The goal of this section is to take the reader from zero-to-situated. Docs should assume that the user has _only_ gone through the initial getting started docs. At the end of this guide, the user will understand the basics of plugin development.
|
||||
|
||||
### Why build plugins?
|
||||
|
||||
This section should answer definitely why you should build a new plugin. The Backstage framework is deeply empowered by plugins and plugins are core to the project's success. Users should walk away from reading this section with a conviction that plugins are the right path for new functionality.
|
||||
|
||||
### Creating a plugin
|
||||
|
||||
This section should be extremely deliberate in showing readers every step of the way to create a plugin using Backstage's best practises. A reader that finishes this section should feel extremely comfortable adding and installing new plugins regardless of their experience with JS/TS and Backstage.
|
||||
|
||||
- Setting up your environment
|
||||
- Scaffolding a new plugin
|
||||
- Installation syntax
|
||||
- Core services
|
||||
- Debugging
|
||||
- Declaration error, `export default` missing
|
||||
- Startup error, `httpRouter` failed to start
|
||||
|
||||
### Sustainable plugin development
|
||||
|
||||
Plugins are not developed in a vacuum. Users should reach for them to solve specific business problems facing their developers, for example, you may be tasked to create
|
||||
|
||||
- a new vendor integration like PagerDuty,
|
||||
- a new plugin backend that talks to an internal service,
|
||||
- etc.
|
||||
|
||||
This section should contain learnings from successful Backstage deployments about how to engage with stakeholders, how/when to iterate on your plugin, and setting yourself up for future success.
|
||||
@@ -1,56 +0,0 @@
|
||||
---
|
||||
id: guides
|
||||
title: Guides for Plugins
|
||||
---
|
||||
|
||||
:::note Note
|
||||
This docs is still a work in progress, many of the guides described below do not exist yet.
|
||||
:::
|
||||
|
||||
## Guides for Plugin Development
|
||||
|
||||
### For Beginners: Introduction to Plugin Development
|
||||
|
||||
This section is designed for those new to plugin development. It covers the basics and provides a foundation for more advanced topics.
|
||||
|
||||
- **Introduction to Plugin Development**
|
||||
- Why build plugins? Introduction to the value and impact of plugins within Backstage.
|
||||
- Detailed guidance on starting and iterating on a plugin development project.
|
||||
- Engaging with the community and stakeholders to propel your project.
|
||||
|
||||
### For Intermediate Users: Scaling and Deploying Your Plugin
|
||||
|
||||
This section helps developers prepare their plugins for broader adoption, emphasizing best practices in monitoring, logging, and performance.
|
||||
|
||||
- **Scaling and Deploying Your Plugin**
|
||||
- Strategies for scaling your plugin for greater adoption.
|
||||
- Best practices for monitoring and logging.
|
||||
- Understand plugin ownership and maintain an inner source mentality.
|
||||
|
||||
### For Advanced Users: Advanced Plugin Customization and Integration
|
||||
|
||||
This is for those ready to explore complex challenges and enhance their plugins with advanced features.
|
||||
|
||||
- **Advanced Plugin Customization and Integration**
|
||||
- Enabling resource-level authorization and interfacing with external services, SCMs, or databases.
|
||||
- In-depth exploration of fostering an inner source mentality and understanding adoption dynamics.
|
||||
- Decision-making frameworks: choosing between developing a new plugin or utilizing an existing open-source solution.
|
||||
- Open-sourcing: How and when to contribute back to the community.
|
||||
|
||||
## Additional Resources and Further Reading
|
||||
|
||||
- **Real-world Implementations and Lessons**
|
||||
|
||||
- [Case studies and examples from the community](https://github.com/backstage/community#newsletters).
|
||||
- Best practices derived from mature implementations.
|
||||
- [Existing open-source community-maintained plugins](https://github.com/backstage/community-plugins).
|
||||
|
||||
- **Resource Compendium**
|
||||
|
||||
- [Backstage Glossary](https://backstage.io/docs/references/glossary) of key terms.
|
||||
- Recommended readings and tools for advanced developers.
|
||||
|
||||
- **Certification and Learning Pathways**
|
||||
- Pathways to deepen your understanding and expertise in plugin development for Backstage.
|
||||
|
||||
Stay tuned for detailed exploration and guidance in each of these modules. We're excited to accompany you on your plugin development journey!
|
||||
@@ -1,18 +0,0 @@
|
||||
<!-- THIS FILE IS NOT INTENDED TO BE DISPLAYED ON THE DOCSITE -->
|
||||
|
||||
## Glossary
|
||||
|
||||
- Page: A single `md` file.
|
||||
- Guide: A number of pages grouped under the same folder.
|
||||
- Progression: Guides are ordered and moving along that order will give you the next guide, for example, "201" will follow "101" or "experienced" will follow "beginner".
|
||||
- Progression level: Explicit guides in a progression, for example, "101" or "beginner"
|
||||
|
||||
## Writing Guidelines
|
||||
|
||||
The goal of these docs is to provide a comprehensive set of guides that developers + admins can use to quickly get up to speed with plugin development, and then refer to as they're developing their own plugins.
|
||||
|
||||
A user that finishes all of these guides will feel comfortable implementing plugins on their own. If additional assistance is required, they should be referred to other sources of information such as Discord, GitHub, source code, or documentation for further support. The user will also understand why/when to build their own plugins, inner-sourcing their developer portal and contributing internal plugins back to the open-source project.
|
||||
|
||||
At the same time, not all users will finish the docs or they may come back to them as required. Individual guides should have strong "abstracts" (what will I learn by reading this guide), table of contents, and "next steps" (what do I need to do next) to guide users to read the most important pieces for their work.
|
||||
|
||||
When writing guide pages, keep it light! These should be instructional docs, and at the same time conversational and a joy to read. Guides should build on each other, when reading through a progression, the reader should feel more comfortable and confident with concepts as they pop up across progression levels. Guides should be standalone, when finishing one level (for example 101), you should be able to immediately jump into the next (201) without additional research or background. Referencing previous progression levels is ok.
|
||||
Reference in New Issue
Block a user