You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: _posts/articles/2021-02-14-setting-up-techdocs-on-backstage.md
+95-84Lines changed: 95 additions & 84 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,206 +5,217 @@ excerpt: "Techdocs is Spotify's homegrown docs like code solution. it allows the
5
5
last_modified_at: Sun Feb 12 14:39:05 CST 2021
6
6
categories: articles
7
7
author: padraig_o_brien
8
-
tags: [backstage, techdocs, roadie, spotify, mkdocs, service catalog]
8
+
tags: [backstage, TechDocs, roadie, spotify, mkdocs, service catalog]
9
9
image:
10
10
path: /images/backstage.jpg
11
11
caption: "[Flickr](https://flic.kr/p/o6Sdy6)"
12
12
comments: false
13
13
share: true
14
14
---
15
-
TechDocs is Spotify’s homegrown docs-like-code solution built directly into Backstage. This means engineers write their documentation in Markdown files which live together with their code. In this post we will walk you through how to setup Backstage and Techdocs.
15
+
TechDocs is Spotify’s homegrown docs-like-code solution built directly into Backstage. [Backstage](https://github.com/backstage/backstage) gives teams one front-end view for all their infrastructure tools, like Google Cloud Platform, Cloud Bigtable, CI pipelines, TensorFlow Extended, and others, all in a consistent, easy-to-use interface, or portal. It's open source software released by Spotify.
16
+
17
+
With TechDocs built into Backstage, all the engineers write their documentation in Markdown files which live together with their code. You can read more about their docs-as-code story in [this article](https://www.docslikecode.com/articles/ten-tips-maintaining-long-term-docs-like-code/). In this post we will walk you through how to setup Backstage and Techdocs.
16
18
17
19
**Table of contents**
18
20
19
-
- Introduction.
20
-
- Basic concepts and structure of backstage and techdocs.
21
-
- Install Backstage.
22
-
- Setup tech docs.
23
-
-Creating and publishing documentation.
24
-
- Publish to cloud storage
25
-
- Recap
21
+
- Introduction
22
+
- Basic concepts and structure of Backstage and TechDocs
23
+
- Install Backstage
24
+
- Setup TechDocs
25
+
-Create and publish documentation
26
+
- Publish to cloud storage (example)
27
+
- Recap and summary
26
28
27
-
## **Introduction**
29
+
## Introduction
28
30
29
-
Backstage is a platform for building developer portals.
31
+
Backstage is a platform for building developer portals, giving one view into developer tools.
30
32
31
-
Its main benefit is allowing you to ship high quality code fast.
33
+
Its main benefit is allowing you to ship high quality code fast thanks to consistent views of your tools and infrastructure.
32
34
33
-
The main features you get out of the box are
35
+
The features you get out of the box are:
34
36
35
-
- Service catalog.
36
-
- Software templates.
37
-
- Plugins which allow you to extend backstage functionality.
38
-
-Techdocs, which is the focus of this post.
37
+
- Service catalog
38
+
- Software templates
39
+
- Plugins which allow you to extend Backstage functionality
40
+
-TechDocs, which is the focus of this post
39
41
40
-
These features allow you to create standards and best practices across teams. It increases the speed of development. It creates a good developer experience for everyone who uses it. You centralise all your tools and info in one place.
42
+
These features allow you to create standards and best practices across teams. It increases the speed of development. It creates a good developer experience for everyone who uses it. You centralize all your tools and information in one place.
41
43
42
-
In this post I will take you through the following
44
+
In this post I will take you through the basic concepts and structure of Backstage and TechDocs, an installation of Backstage including the setup of TechDocs, creating and publishing documentation, all on a local machine on MacOS.
43
45
44
-
- Learn basic concepts and structure of backstage and techdocs
45
-
- Install Backstage
46
-
- Setup tech docs
47
-
- Creating and publishing documentation.
48
-
- All on local machine
46
+
## Basic concepts and structures of Backstage and TechDocs
49
47
50
-
## **Basics concepts and structures of backstage and techdocs**
48
+
The focus of this article is TechDocs, so I will go through the main features at a high level.
51
49
52
-
The focus of this article is techdocs so i will go through the other main features at a high level.
50
+
- Service catalog - It keeps track of ownership and metadata for all the software in your ecosystem. Backstage does this by putting metadata in YAML files stored together with your code. You process these files and then you can visualise the catalog in Backstage. This catalog enables your teams to manage and maintain the software they own, making the software discoverable.
51
+
- Software templates - This feature allows you to create templates or skeletons of code. These templates are published to GitHub.
52
+
- Plugins - Allow you to integrate third party tools or any kind of infrastructure into Backstage. They are open source and you can view a list [here](https://backstage.io/plugins).
53
+
- Techdocs - Yay, finally, why we are here. Techdocs is Spotify's homegrown docs like code solution. It allows the user to store documentation near the relevant code, thus allowing the docs to be easily discovered and maintained.
53
54
54
-
- Service catalog. It keeps track of ownership and metadata for all the software in your ecosystem. it does this by putting metadata in YAML files stored together with your code. You process these files and then you can visualise the catalog in backstage. This will enable your teams to manage and maintain the software they own. it also makes the software discoverable.
55
-
- Software templates - This feature allows you to create templates or skeletons of code. These templates are published to github.
56
-
- Plugins - Allow you to integrate third part tools or any kind of infrastructure into backstage. They are open source and you can view a list [here](https://backstage.io/plugins)
57
-
- Techdocs- yay, finally, why we are here. Techdocs is Spotify's homegrown docs like code solution. it allows the user to store documentation to near code thus allowing it to be easily discovered.
55
+
When you deploy Backstage with Techdocs enabled you get a basic out of the box experience.
58
56
59
-
When you deploy backstage with Techdocs enabled you get a basic out of the box experience.
57
+
At its core, TechDocs is an MKDocs plugin with other MkDocs plugins and Python Markdown extensions which allows it to standardize the configuration of MkDocs used for TechDocs.
60
58
61
-
At its core it is MKDocs plugin and other MkDocs plugins and Python Markdown extensions which allows it to standardize the configuration of MkDocs used for TechDocs.
59
+
You can see the source code for TechDocs[here](https://github.com/backstage/mkdocs-TechDocs-core).
62
60
63
-
You can see the code [here](https://github.com/backstage/mkdocs-techdocs-core)
61
+
The other moving parts are:
64
62
65
-
The other moving parts are
63
+
- The TechDocs container which can be found on DockerHub at https://hub.docker.com/r/spotify/techdocs, which builds static content through MKDocs.
64
+
- The Techdocs backend plugin which is the backend part of the TechDocs plugin.
65
+
- The Techdocs CLI, a handy command line tool for managing TechDocs sites in Backstage.
66
+
- The Techdocs reader, it fetches remotes pages, runs "transforms" against them, and renders them in a shadow DOM.
67
+
- The Transforms API takes in parameters from the reader component and returns a function which gets passed the DOM of the fetched page.
66
68
67
-
- The techdocs container which can be found on Docker-hub, It builds static content through MKDocs
68
-
- The Techdocs backend plugin This is the backend part of the techdocs plugin.
69
-
- The Techdocs CLI, Command line tool for managing techdocs sites in backstage
70
-
- The Techdocs reader, it fetch's remotes pages , run transformers against them and renders them in a shadow DOM
71
-
- Transformers API is a function that takes in parameters from the reader component and returns a function which gets passed the dom of the fetched page.
When you open a TechDocs site, a request is made. The TechDocs reader calls the TechDocs-backend with the entity id and the path of the current page. The response contains the static content. The static content contains HTML and CSS, and any JavaScript is removed for security reasons.
76
74
77
-
When you open a techdocs sites a request is made the techdocs reader calls the techdocs-backend with the entity id and the path of the current page, the response contains the static content
75
+
Transforms are then applied which modify the generated static HTML files for a number of reasons like removing certain headers and so on.
78
76
79
-
The static content contains HTML and CSS, javascript is removed for security reasons
77
+
For the following instructions, since we are using a local install for demonstration and trial, we will use the local file storage, but in production you would use cloud storage like S3.
80
78
81
-
Transforms are then applied which modiy the generated static HTML files for a number of reasons like removing certain headers etc
79
+
## Install Backstage
82
80
83
-
For the following instructions we will use the local file storage but it is better to use cloud storage like S3.
81
+
> If you have any difficulty with the installation, you can [log an Issue in the Backstage repository](https://github.com/backstage/backstage/issues).
84
82
85
-
##**Install Backstage**
83
+
### Prerequisites
86
84
87
-
### Perquisites
88
-
Mac running MacOS
85
+
* Mac running MacOS
89
86
90
-
Node version 14.x
87
+
*Node Version Manager (nvm) so that you can ensure you're using Node version 14. Run: `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.37.2/install.sh | bash` or `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.37.2/install.sh | zsh` on MacOS Catalina and newer.
91
88
92
-
cookiecutter
89
+
* Node version 14.x (Cannot use Node version 15.x) (You can use `brew install node` to install on MacOS if needed.) Run `nvm use --lts` so that you can run Node version 14.15.5 for this demo.
93
90
94
-
If you already have backstage installed then skip this.
91
+
* Yarn (Use `brew install yarn` for this demo.)
92
+
93
+
If you already have Backstage installed, then you skip this "create-app" step. First, create the initial app in any directory you choose:
95
94
96
95
```jsx
97
96
npx @backstage/create-app
98
97
```
99
98
100
-
You are asked some questions on setup, The recommendation for this tutorial is to go with SQLLite.
99
+
This will take a few minutes.
100
+
101
+
You are asked some questions on setup. The recommendation for this local tutorial is to go with SQLLite by using the down arrow when prompted.
101
102
102
-
103
+
103
104
104
-
If successful you will see this message
105
+
If successful you see this message:
105
106
106
107
107
108
108
-
cd into your directory and run
109
+
Change into your created app's directory, the name you used for the app. In this example the name is `infraportal`:
110
+
111
+
```
112
+
cd infraportal
113
+
```
114
+
115
+
Then run:
109
116
110
117
```jsx
111
118
yarn workspace backend start
112
119
```
113
120
114
121
115
122
116
-
Open a new terminal window and
123
+
Open a new terminal window and change directories to the `infraportal` where you created the app.
124
+
```
125
+
cd ~/src/backstage/infraportal
126
+
```
127
+
128
+
Then start the app with this command:
117
129
118
130
```jsx
119
-
run yarn start
131
+
yarn run start
120
132
```
121
133
122
134
123
135
124
-
If successful a browser window will open up and you should be presented with a window
136
+
If successful, a browser window opens and you should be presented with a window.
125
137
126
-
138
+
127
139
128
-
Well done, you have successfully installed backstage on your machine.
140
+
Well done, you have successfully installed Backstage on your local machine.
129
141
130
142
## Setup TechDocs
131
143
132
-
Historically you had to manually add Techdocs , the latest version of create-app bundles tech docs.
144
+
Historically you had to manually add Techdocs, but now the latest version of `create-app` bundles TechDocs.
133
145
134
-
to verify this you should be able to see entries for the following plugin
135
-
136
-
```jsx
137
-
'@backstage/plugin-techdocs';
138
-
139
-
```
140
-
141
-
in the following files
146
+
To verify this setup, you should be able to see entries for the plugin `'@backstage/plugin-TechDocs';` in the following files:
142
147
143
148
```jsx
144
149
packages/app/src/plugins.ts
145
150
packages/app/src/App.tsx
146
151
```
147
152
148
-
## Creating and publishing techdocs
153
+
## Creating and publishing TechDocs
149
154
150
-
To create docs manually from scratch click on create component
155
+
To create docs manually from scratch, click on Create component:
151
156
152
157
153
158
154
-
From here choose the Documentation template
159
+
From here choose the Documentation template.
155
160
156
161
157
162
158
-
Fill out Name and Description
163
+
Fill out a Name and Description.
159
164
160
165
161
166
162
-
Type in the owner, the Github repo you want to call it , ensure their is no Github repo that exists with the same name or the Templater will fail
167
+
Have a GitHub org or owner and a GitHub repo ready to use for your docs. Have a [GitHub token created](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) and available in your environment as `GITHUB_TOKEN`. Type in the GitHub owner and the GitHub repo you want to use. Make sure there is no GitHub repo that exists with the same name or the Templater will fail.
163
168
164
169
165
170
166
171
Once you click on create you will be presented with a Create component status popup.
167
172
168
173
169
174
170
-
Once the repository has been published to github the create component status popup will go green like below.
175
+
Once the repository has been published to GitHub, the Create component status popup will show green like below.
171
176
172
177
173
178
174
179
You will be able to navigate to the docs.
175
180
176
181
177
182
178
-
If it is the first time you are loading them you could receive this message while it converts from MD to html
183
+
If this is the first time you are loading the docs, you could receive this message while it converts from Markdown to HTML.
179
184
180
185
181
186
182
-
Here is what you will be presented with.
187
+
Here is a screenshot of what you will be presented with.
183
188
184
189
185
190
186
-
You now have techdocs up and running on your machine, if you want to view the files manually they are located at the following location on you machine
191
+
You now have TechDocs up and running on your machine. Well done. If you want to view the files and work on them locally they are located at the following location on your machine:
The recommended setup is to place the output on to cloud storage and not on the local machine
197
+
Your workflow would be to work on the files, preview locally, then commit your changes and send in pull requests, using your team's Git workflows.
193
198
194
199
## Publish to cloud storage
195
200
201
+
The recommended setup is to place the output on to cloud storage such as S3, and not on the local machine, so let's look at that.
202
+
203
+
> Note: This section is just an overview, and not a full tutorial, because there are a lot of prerequisites for setting up cloud storage. If you're interested, read the AWS S3 documentation about [Creating a bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) and the [Buckets overview](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingBucket.html).
204
+
196
205
197
206
198
-
When you startup backstage you should see this message in the logs to confirm you are using cloud storage
207
+
When you startup Backstage you should see this message in the logs to confirm you are using cloud storage:
199
208
200
209
201
210
202
211
You will also see the content in the S3 bucket.
203
212
204
213
205
214
206
-
## Recap
215
+
## Recap and summary
216
+
217
+
In summary, we went through an introduction on Backstage, TechDocs, and how to publish TechDocs locally. We took a look at the cloud storage option with some screenshots showing S3. To learn more about Backstage I would recommend visiting [https://backstage.io](https://backstage.io) or if you want to learn more about TechDocs then [https://backstage.io/docs/features/TechDocs/TechDocs-overview](https://backstage.io/docs/features/TechDocs/TechDocs-overview) offers a great overview.
207
218
208
-
In summary, we went through an introduction on backs stage, techdocs and how to publish techdocs locally and to cloud storage via s3. if you want to learn more about backstage i would recommend visiting [https://backstage.io](https://backstage.io) or if you want to learn more about techdocs then [https://backstage.io/docs/features/techdocs/techdocs-overview](https://backstage.io/docs/features/techdocs/techdocs-overview)
219
+
You can also read about the gains the team at Spotify has seen since using TechDocs for all their documentation in [Ten tips for maintaining a long-term relationship with docs like code](https://www.docslikecode.com/articles/ten-tips-maintaining-long-term-docs-like-code/). TechDocs has a really nice [project board in GitHub,](https://github.com/orgs/backstage/projects/1#card-54927264) so if you're interested in working on it yourself, take a look.
209
220
210
-
If you like the idea of backstage but don't want the inconvenience of managing backstage yourself then i would check out [https://roadie.io](https://roadie.io).
221
+
If you like the idea of Backstage but don't want the inconvenience of managing Backstage yourself, then check out [https://roadie.io](https://roadie.io). Thanks for taking a look at this tutorial and happy documenting!
0 commit comments