Skip to content

Commit 870fbc9

Browse files
padraigobrienpadraigobrien
committed
Adding Backstage Techdocs article
1 parent 863265e commit 870fbc9

2 files changed

Lines changed: 202 additions & 1 deletion

File tree

‎.jekyll-cache/Jekyll/Cache/Jekyll--Converters--Markdown/32/849986eb152666d1dc3ad091384024540ee5f0cc15dad07a8279207ceeacc9‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
I"�(<p>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.</p>
2+
3+
<p><strong>Table of contents</strong></p>
4+
5+
<ul>
6+
<li>Introduction.</li>
7+
<li>Basic concepts and structure of backstage and techdocs.</li>
8+
<li>Install Backstage.</li>
9+
<li>Setup tech docs.</li>
10+
<li>Creating and publishing documentation.</li>
11+
<li>Publish to cloud storage</li>
12+
<li>Recap</li>
13+
</ul>
14+
15+
<h2 id="introduction"><strong>Introduction</strong></h2>
16+
17+
<p>Backstage is a platform for building developer portals.</p>
18+
19+
<p>Its main benefit is allowing you to ship high quality code fast.</p>
20+
21+
<p>The main features you get out of the box are</p>
22+
23+
<ul>
24+
<li>Service catalog.</li>
25+
<li>Software templates.</li>
26+
<li>Plugins which allow you to extend backstage functionality.</li>
27+
<li>Techdocs, which is the focus of this post.</li>
28+
</ul>
29+
30+
<p>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.</p>
31+
32+
<p>In this post I will take you through the following</p>
33+
34+
<ul>
35+
<li>Learn basic concepts and structure of backstage and techdocs</li>
36+
<li>Install Backstage</li>
37+
<li>Setup tech docs</li>
38+
<li>Creating and publishing documentation.</li>
39+
<li>All on local machine</li>
40+
</ul>
41+
42+
<h2 id="basics-concepts-and-structures-of-backstage-and-techdocs"><strong>Basics concepts and structures of backstage and techdocs</strong></h2>
43+
44+
<p>The focus of this article is techdocs so i will go through the other main features at a high level.</p>
45+
46+
<ul>
47+
<li>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.</li>
48+
<li>Software templates - This feature allows you to create templates or skeletons of code. These templates are published to github.</li>
49+
<li>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 <a href="https://backstage.io/plugins">here</a></li>
50+
<li>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.</li>
51+
</ul>
52+
53+
<p>When you deploy backstage with Techdocs enabled you get a basic out of the box experience.</p>
54+
55+
<p>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.</p>
56+
57+
<p>You can see the code <a href="https://github.com/backstage/mkdocs-techdocs-core">here</a></p>
58+
59+
<p>The other moving parts are</p>
60+
61+
<ul>
62+
<li>The techdocs container which can be found on Docker-hub, It builds static content through MKDocs</li>
63+
<li>The Techdocs backend plugin This is the backend part of the techdocs plugin.</li>
64+
<li>The Techdocs CLI, Command line tool for managing techdocs sites in backstage</li>
65+
<li>The Techdocs reader, it fetch’s remotes pages , run transformers against them and renders them in a shadow DOM</li>
66+
<li>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.</li>
67+
</ul>
68+
69+
<p>Architecture</p>
70+
71+
<p><img src="https://backstage.io/docs/assets/techdocs/architecture-basic.drawio.svg" alt="Architecture diagram" /></p>
72+
73+
<p>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</p>
74+
75+
<p>The static content contains HTML and CSS, javascript is removed for security reasons</p>
76+
77+
<p>Transforms are then applied which modiy the generated static HTML files for a number of reasons like removing certain headers etc</p>
78+
79+
<p>For the following instructions we will use the local file storage but it is better to use cloud storage like S3.</p>
80+
81+
<h2 id="install-backstage"><strong>Install Backstage</strong></h2>
82+
83+
<h3 id="perquisites">Perquisites</h3>
84+
<p>Mac running MacOS</p>
85+
86+
<p>Node version 14.x</p>
87+
88+
<p>cookiecutter</p>
89+
90+
<p>If you already have backstage installed then skip this.</p>
91+
92+
<div class="language-jsx highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nx">npx</span> <span class="p">@</span><span class="nd">backstage</span><span class="sr">/create-ap</span><span class="err">p
93+
</span></code></pre></div></div>
94+
95+
<p>You are asked some questions on setup, The recommendation for this tutorial is to go with SQLLite.</p>
96+
97+
<p><img src="/images/techdocs/Untitled.png" alt="npx install" /></p>
98+
99+
<p>If successful you will see this message</p>
100+
101+
<p><img src="/images/techdocs/01.png" alt="successful" /></p>
102+
103+
<p>cd into your directory and run</p>
104+
105+
<div class="language-jsx highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nx">yarn</span> <span class="nx">workspace</span> <span class="nx">backend</span> <span class="nx">start</span>
106+
</code></pre></div></div>
107+
108+
<p><img src="/images/techdocs/02.png" alt="yarn workspace" /></p>
109+
110+
<p>Open a new terminal window and</p>
111+
112+
<div class="language-jsx highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nx">run</span> <span class="nx">yarn</span> <span class="nx">start</span>
113+
</code></pre></div></div>
114+
115+
<p><img src="/images/techdocs/03.png" alt="yarn start" /></p>
116+
117+
<p>If successful a browser window will open up and you should be presented with a window</p>
118+
119+
<p><img src="/images/techdocs/04.png" alt="successfull register" /></p>
120+
121+
<p>Well done, you have successfully installed backstage on your machine.</p>
122+
123+
<h2 id="setup-techdocs">Setup TechDocs</h2>
124+
125+
<p>Historically you had to manually add Techdocs , the latest version of create-app bundles tech docs.</p>
126+
127+
<p>to verify this you should be able to see entries for the following plugin</p>
128+
129+
<div class="language-jsx highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="dl">'</span><span class="s1">@backstage/plugin-techdocs</span><span class="dl">'</span><span class="p">;</span>
130+
131+
</code></pre></div></div>
132+
133+
<p>in the following files</p>
134+
135+
<div class="language-jsx highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nx">packages</span><span class="o">/</span><span class="nx">app</span><span class="o">/</span><span class="nx">src</span><span class="o">/</span><span class="nx">plugins</span><span class="p">.</span><span class="nx">ts</span>
136+
<span class="nx">packages</span><span class="o">/</span><span class="nx">app</span><span class="o">/</span><span class="nx">src</span><span class="o">/</span><span class="nx">App</span><span class="p">.</span><span class="nx">tsx</span>
137+
</code></pre></div></div>
138+
139+
<h2 id="creating-and-publishing-techdocs">Creating and publishing techdocs</h2>
140+
141+
<p>To create docs manually from scratch click on create component</p>
142+
143+
<p><img src="/images/techdocs/05.png" alt="manuall" /></p>
144+
145+
<p>From here choose the Documentation template</p>
146+
147+
<p><img src="/images/techdocs/06.png" alt="template" /></p>
148+
149+
<p>Fill out Name and Description</p>
150+
151+
<p><img src="/images/techdocs/07.png" alt="Name Desc" /></p>
152+
153+
<p>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</p>
154+
155+
<p><img src="/images/techdocs/08.png" alt="owner" /></p>
156+
157+
<p>Once you click on create you will be presented with a Create component status popup.</p>
158+
159+
<p><img src="/images/techdocs/09.png" alt="create component" /></p>
160+
161+
<p>Once the repository has been published to github the create component status popup will go green like below.</p>
162+
163+
<p><img src="/images/techdocs/10.png" alt="popup" /></p>
164+
165+
<p>You will be able to navigate to the docs.</p>
166+
167+
<p><img src="/images/techdocs/11.png" alt="navigate" /></p>
168+
169+
<p>If it is the first time you are loading them you could receive this message while it converts from MD to html</p>
170+
171+
<p><img src="/images/techdocs/12.png" alt="loading" /></p>
172+
173+
<p>Here is what you will be presented with.</p>
174+
175+
<p><img src="/images/techdocs/13.png" alt="results" /></p>
176+
177+
<p>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</p>
178+
179+
<div class="language-jsx highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nx">backstage</span><span class="o">/</span><span class="nx">node_modules</span><span class="o">/</span><span class="p">@</span><span class="nd">backstage</span><span class="sr">/plugin-techdocs-backend/</span><span class="kd">static</span><span class="sr">/docs/</span><span class="k">default</span><span class="sr">/Component/</span>
180+
</code></pre></div></div>
181+
182+
<p>The recommended setup is to place the output on to cloud storage and not on the local machine</p>
183+
184+
<h2 id="publish-to-cloud-storage">Publish to cloud storage</h2>
185+
186+
<p><img src="/images/techdocs/14.png" alt="cloud" /></p>
187+
188+
<p>When you startup backstage you should see this message in the logs to confirm you are using cloud storage</p>
189+
190+
<p><img src="/images/techdocs/15.png" alt="registered" /></p>
191+
192+
<p>You will also see the content in the S3 bucket.</p>
193+
194+
<p><img src="/images/techdocs/16.png" alt="s3" /></p>
195+
196+
<h2 id="recap">Recap</h2>
197+
198+
<p>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 <a href="https://backstage.io">https://backstage.io</a> or if you want to learn more about techdocs then <a href="https://backstage.io/docs/features/techdocs/techdocs-overview">https://backstage.io/docs/features/techdocs/techdocs-overview</a></p>
199+
200+
<p>If you like the idea of backstage but don’t want the inconvenience of managing backstage yourself then i would check out <a href="https://roadie.io">https://roadie.io</a>.</p>
201+
:ET

‎_posts/articles/2021-02-14-setting-up-techdocs-on-backstage.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -207,4 +207,4 @@ You will also see the content in the S3 bucket.
207207

208208
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)
209209

210-
If you like the idea of backstage but don't want the inconvenience of managing backstage yourself then i would check out Roadie.io.
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).

0 commit comments

Comments
 (0)