Skip to content

Commit

Permalink
feat: A few last fixes (#554)
Browse files Browse the repository at this point in the history
* feat: A few last fixes

* chore: Match capitalization for all exercise titles
  • Loading branch information
SloaneTribble authored Jul 1, 2024
1 parent 6fb3649 commit 32ebaf0
Show file tree
Hide file tree
Showing 4 changed files with 10 additions and 10 deletions.
6 changes: 3 additions & 3 deletions docs/9-platform-engineering/9.1-backstage.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,13 +29,13 @@ docs/9-platform-engineering/9.1-backstage.md:

# Backstage

Platform teams are responsible for managing an organization's IDP. As mentioned in the overview section this software can be an API, CLI, or GUI but needs to offer teams self-service tools that adhere to the companies best practices and standards.
Platform teams are responsible for managing an organization's IDP. As mentioned in the overview section this software can be an API, CLI, or GUI but needs to offer teams self-service tools that adhere to the company's best practices and standards.

In March 2020 Spotify open sourced their internal developer platform Backstage and donated the project to the Cloud Native Computing Foundation (CNCF). Backstage is a web app that is designed to serve as a 'one stop shop' for all your developer needs. Through its key features of the Software Catalog, Templates, and TechDocs users can get a detailed overview of an organization's technology landscape, easily discover internal projects and documentation, and use a simplified process to create new projects that adhere to the company's standards.

## Backstage's Design

Backstage is a monorepo React application that is written in TypeScript. Backstage is constructed out of three parts.
Backstage is a monorepo React application that is written in TypeScript, and is constructed out of three parts.

![Parts of backstage](https://backstage-spotify-com.spotifycdn.com/_next/static/media/IMG_key_terms.72c69cd1.png ':class=img-center :alt=parts of backstage')

Expand Down Expand Up @@ -68,7 +68,7 @@ a GitHub org to play around with. Each person going through the bootcamp will ne

1. Follow [GitHubs docs](https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch) and create a new Organization (Free)

### Exercise 2: Stand up local instance of Backstage
### Exercise 2: Stand up a Local Instance of Backstage

1. Follow Backstage's official [Getting Started](https://backstage.spotify.com/learn/standing-up-backstage/standing-up-backstage/1-intro/) guide
> Skip setting up the PostgresSQL instance
Expand Down
8 changes: 4 additions & 4 deletions docs/9-platform-engineering/9.1.1-software-catalog.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ To solve this problem, Spotify created Backstage, central to which is the Softwa
Please read more about it on the [Backstage website](https://backstage.io/docs/features/software-catalog/).
![backstage software catalog](./img9/software-catalog.png ':class=img-center :alt= Backstage Software Catalog')

### Exercise 1: Register an entity to Backstage
### Exercise 1: Register an Entity to Backstage

In Backstage, entities represent different types of resources within your system. They are defined using YAML files and registered in the Backstage catalog. Each entity type has a specific purpose and schema.

Expand All @@ -55,23 +55,23 @@ In Backstage, entities represent different types of resources within your system

2. Continue following the above guide to manually register a component entity to your Backstage instance. *You may find it helpful for future exercises to take note of the information that is provided alongside your components in the UI, and consider where it comes from.*

### Exercise 2: Configure automatic catalog ingestion
### Exercise 2: Configure Automatic Catalog Ingestion

While manually registering entities is fairly straightforward, it wouldn't make much sense to do this for a system made up of any more than a few components because it would quickly become tedious and time-consuming. Thankfully there is a way to automate this process. We can set up Backstage to periodically inspect a given location, such as GitHub, for information that it can use to automatically generate these entities.

1. Configure your Backstage instance to automatically register entities based on repos that it detects within a GitHub organization that you own.

?> See [GitHub Discovery](https://backstage.io/docs/integrations/github/discovery/) for a useful guide.

### Exercise 3: Generate a dependency graph
### Exercise 3: Generate a Dependency Graph

Hopefully you enjoyed the contrast between manually and automatically registering entities. In a similar vein, another useful feature of Backstage is its ability to leverage `catalog-info.yaml` files to automatically generate dependency graphs depicting the relationship between entities in a software ecosystem. The visual aid provided by these graphs can help users quickly understand complex systems. For example, if a developer needs to make a change to a particular service, they can look at that service's dependency graph to know what (and who) else might be affected by such a change.

1. Fork the [dks-ui](https://github.com/liatrio/dks-ui) and [dks-api](https://github.com/liatrio/dks-api) repos into a GitHub organization that you own.
2. Add or modify each repo's `catalog-info.yaml` to define its relationship to the other repo. In other words, we want to be sure that each entity references the other.
3. Verify that within your Backstage instance, each of the two entities' dependency graphs shows a relation to the other entity.

### Exercise 4: Generate an OpenAPI definition
### Exercise 4: Generate an OpenAPI Definition

The OpenAPI Specifications provide a formal standard for describing HTTP APIs. Following this standard provides many advantages, including helping people to systematically understand how a given API works on its own and in relation to other APIs, and allowing client code to be automatically generated which can correctly interact with the API.

Expand Down
4 changes: 2 additions & 2 deletions docs/9-platform-engineering/9.1.2-techdocs.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ docs/9-platform-engineering/9.1.2-techdocs.md:
category: TechDocs
estReadingMinutes: 10
exercises:
- name: Enable documentation for an already existing entity
- name: Enable Documentation for an Existing Entity
description: |
This exercise instructs students to add the bare minimum amount of files needed for their Backstage instance to generate an MkDocs site and associate it with an entity in their Software Catalog. Extra credit is offered for studying Backstage's ability to search within TechDocs stored in the Catalog -- the basic setup we point students towards in this exercise can lead to a search-related bug which is valuable for understanding the different ways Backstage can be configured to manage TechDocs.
estMinutes: 40
Expand All @@ -20,7 +20,7 @@ This solution is built on top of the *[docs like code approach](https://www.docs

Backstage enables the *docs like code approach* by providing tools that can automatically generate an easy-to-navigate documentation website and associate it with one or more entities in a Software Catalog. This can be achieved in multiple ways -- for example, you can [set up automated documentation with your Software Templates](https://backstage.io/docs/features/techdocs/how-to-guides/#how-to-add-the-documentation-setup-to-your-software-templates) so that any Software Templates built on your Backstage instance will come with an associated docs website. You can also [configure CI/CD to generate and publish TechDocs sites](https://backstage.io/docs/features/techdocs/configuring-ci-cd).

### Exercise: Enable documentation for an already existing entity
### Exercise: Enable Documentation for an Existing Entity

While TechDocs can be used in a variety of ways, we will start with something simple.

Expand Down
2 changes: 1 addition & 1 deletion docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -1111,7 +1111,7 @@ docs/9-platform-engineering/9.1.2-techdocs.md:
category: TechDocs
estReadingMinutes: 10
exercises:
- name: Enable documentation for an already existing entity
- name: Enable Documentation for an Existing Entity
description: >
This exercise instructs students to add the bare minimum amount of files
needed for their Backstage instance to generate an MkDocs site and
Expand Down

0 comments on commit 32ebaf0

Please sign in to comment.