Merge branch 'master' into new-routing-jenkins
This commit is contained in:
Tim Jacomb
Binary file not shown.
|
Before Width: | Height: | Size: 303 KiB After Width: | Height: | Size: 102 KiB |
@@ -1,4 +1,7 @@
|
||||
# Installing in your Backstage App
|
||||
---
|
||||
id: installation
|
||||
title: Installing in your Backstage App
|
||||
---
|
||||
|
||||
The catalog plugin comes in two packages, `@backstage/plugin-catalog` and
|
||||
`@backstage/plugin-catalog-backend`. Each has their own installation steps,
|
||||
|
||||
@@ -105,13 +105,6 @@ curl \
|
||||
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, run the following to load those templates:
|
||||
|
||||
```
|
||||
yarn lerna run mock-data
|
||||
```
|
||||
|
||||
The `type` field which is chosen in the request to add the `template.yaml` to
|
||||
the Service Catalog here, will be come the `PreparerKey` which will be used to
|
||||
select the `Preparer` when creating a job.
|
||||
|
||||
@@ -15,12 +15,15 @@ like GitHub.
|
||||
|
||||
### Getting Started
|
||||
|
||||
The Software Templates are available under `/create`. If you've followed
|
||||
[Installing in your Backstage App](./installation.md) in your separate App or
|
||||
[Getting Started with Backstage](../../getting-started) for this repo, you
|
||||
should be able to reach `http://localhost:3000/create`.
|
||||
> Be sure to have covered [Installing in your Backstage App](./installation.md)
|
||||
> for your separate App or
|
||||
> [Getting Started with Backstage](../../getting-started) for this repo before
|
||||
> proceeding.
|
||||
|
||||
You should get something that looks similar to this:
|
||||
The Software Templates are available under `/create`. For local development you
|
||||
should be able to reach them at `http://localhost:3000/create`.
|
||||
|
||||
Once there, you should see something that looks similar to this:
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -1,4 +1,7 @@
|
||||
# Installing in your Backstage App
|
||||
---
|
||||
id: installation
|
||||
title: Installing in your Backstage App
|
||||
---
|
||||
|
||||
The scaffolder plugin comes in two packages, `@backstage/plugin-scaffolder` and
|
||||
`@backstage/plugin-scaffolder-backend`. Each has their own installation steps,
|
||||
@@ -174,9 +177,6 @@ docs on creating private GitHub access tokens is available
|
||||
Note that the need for private GitHub access tokens will be replaced with GitHub
|
||||
Apps integration further down the line.
|
||||
|
||||
> **Right now it is only possible to scaffold repositories inside GitHub
|
||||
> organizations, and not under personal accounts.**
|
||||
|
||||
The GitHub access token is passed along using the `GITHUB_ACCESS_TOKEN`
|
||||
environment variable.
|
||||
|
||||
|
||||
@@ -6,14 +6,11 @@ sidebar_label: FAQ
|
||||
|
||||
This page answers frequently asked questions about [TechDocs](README.md).
|
||||
|
||||
_Got a question that you think others might be interested in knowing the answer
|
||||
to? Edit this file
|
||||
[here](https://github.com/spotify/backstage/edit/master/docs/features/techdocs/FAQ.md)._
|
||||
|
||||
## Technology
|
||||
|
||||
- [What static site generator is TechDocs using?](./#what-static-site-generator-is-techdocs-using)
|
||||
- [What is the mkdocs-techdocs-core plugin?](./#what-is-the-mkdocs-techdocs-core-plugin)
|
||||
- [What static site generator is TechDocs using?](#what-static-site-generator-is-techdocs-using)
|
||||
- [What is the mkdocs-techdocs-core plugin?](#what-is-the-mkdocs-techdocs-core-plugin)
|
||||
- [Does TechDocs support file formats other than Markdown (e.g. rst, asciidoc)?](#does-techdocs-support-file-formats-other-than-markdown-eg-rst-asciidoc-)
|
||||
|
||||
#### What static site generator is TechDocs using?
|
||||
|
||||
@@ -30,3 +27,10 @@ package is a MkDocs Plugin that works like a wrapper around multiple MkDocs
|
||||
plugins (e.g.
|
||||
[MkDocs Monorepo Plugin](https://github.com/spotify/mkdocs-monorepo-plugin)) as
|
||||
well as a selection of Python Markdown extensions that TechDocs supports.
|
||||
|
||||
#### Does TechDocs support file formats other than Markdown (e.g. rst, asciidoc) ?
|
||||
|
||||
Not right now. We are currently using MkDocs to generate the documentation from
|
||||
source. So, they have to be in Markdown format. However, in future we want to
|
||||
support other alternatives to MkDocs. That will make it possible to use other
|
||||
file formats.
|
||||
|
||||
@@ -8,16 +8,21 @@ sidebar_label: Overview
|
||||
|
||||
<!-- Intro, backstory, etc.: -->
|
||||
|
||||
Wait, what is TechDocs? TechDocs is Spotify’s homegrown docs-like-code solution
|
||||
built directly into Backstage. Today, it is now one of the core products in
|
||||
Spotify’s developer experience offering with 2,400+ documentation sites and
|
||||
1,000+ engineers using it daily.
|
||||
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.
|
||||
|
||||
Today, it is one of the core products in Spotify’s developer experience offering
|
||||
with 2,400+ documentation sites and 1,000+ engineers using it daily. Read more
|
||||
about TechDocs and the philosophy in its
|
||||
[announcement blog post](https://backstage.io/blog/2020/09/08/announcing-tech-docs).
|
||||
🎉
|
||||
|
||||
## Features
|
||||
|
||||
- A centralized place to discover documentation.
|
||||
- A centralized place to discover and read documentation.
|
||||
|
||||
- A clear end-to-end docs-like-code solution. (_Coming soon in V.1_)
|
||||
- A clear end-to-end docs-like-code solution.
|
||||
|
||||
- A tightly coupled feedback loop with the developer workflow. (_Coming soon in
|
||||
V.3_)
|
||||
@@ -26,12 +31,12 @@ Spotify’s developer experience offering with 2,400+ documentation sites and
|
||||
|
||||
## Project roadmap
|
||||
|
||||
| Version | Description |
|
||||
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [TechDocs V.0 ✅][v0] | Read docs in Backstage - Enable anyone to get a reader experience working in Backstage. [See V.0 Use Cases.](./#techdocs-v0) |
|
||||
| [TechDocs V.1 🚧][v1] | TechDocs end to end (alpha) - Alpha of TechDocs that you can use end to end - and contribute to. [See V.1 Use Cases.](./#techdocs-v1) |
|
||||
| [TechDocs V.2 🔮⌛][v2] | Platform stability and compatibility improvements. [See V.2 Use Cases.](./#techdocs-v2) |
|
||||
| TechDocs V.3 🔮⌛ | Widget Architecture - TechDocs widget architecture available, so the community can create their own customized features. |
|
||||
| Version | Description |
|
||||
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [TechDocs V.0 ✅][v0] | Read docs in Backstage - Enable anyone to get a reader experience working in Backstage. [See V.0 Use Cases.](#techdocs-v0) |
|
||||
| [TechDocs V.1 ✅][v1] | TechDocs end to end (alpha) - Alpha of TechDocs that you can use end to end - and contribute to. [See V.1 Use Cases.](#techdocs-v1) |
|
||||
| [TechDocs V.2 🔮⌛][v2] | Platform stability and compatibility improvements. [See V.2 Use Cases.](#techdocs-v2) |
|
||||
| TechDocs V.3 🔮⌛ | Widget Architecture - TechDocs widget architecture available, so the community can create their own customized features. |
|
||||
|
||||
[v0]: https://github.com/spotify/backstage/milestone/15
|
||||
[v1]: https://github.com/spotify/backstage/milestone/16
|
||||
@@ -44,7 +49,7 @@ Spotify’s developer experience offering with 2,400+ documentation sites and
|
||||
#### TechDocs V.0
|
||||
|
||||
- As a user I can navigate to a manually curated docs explore page.
|
||||
- As a user I can navigte to and read mock documentation that is manually
|
||||
- As a user I can navigate to and read mock documentation that is manually
|
||||
uploaded by the TechDocs core team.
|
||||
|
||||
#### TechDocs V.1
|
||||
@@ -101,7 +106,3 @@ more to come...
|
||||
https://github.com/spotify/backstage/blob/master/packages/techdocs-container
|
||||
[techdocs/cli]:
|
||||
https://github.com/spotify/backstage/blob/master/packages/techdocs-cli
|
||||
|
||||
## TechDocs Big Picture
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
---
|
||||
id: architecture
|
||||
title: Architecture
|
||||
---
|
||||
|
||||
|
||||
@@ -8,9 +8,9 @@ solution in Backstage.
|
||||
|
||||
### TechDocs Core Plugin
|
||||
|
||||
The TechDocs Core Plugin is a MkDocs plugin created as a wrapper around multiple
|
||||
MkDocs plugins and Python Markdown extensions to standardize the configuration
|
||||
of MkDocs used for TechDocs.
|
||||
The TechDocs Core Plugin is an [MkDocs](https://www.mkdocs.org/) plugin created
|
||||
as a wrapper around multiple MkDocs plugins and Python Markdown extensions to
|
||||
standardize the configuration of MkDocs used for TechDocs.
|
||||
|
||||
[TechDocs Core](https://github.com/spotify/backstage/blob/master/packages/techdocs-container/techdocs-core/README.md)
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@ This section will guide you through:
|
||||
- [Manually add documentation setup to already existing repository](#manually-add-documentation-setup-to-already-existing-repository)
|
||||
- [Writing and previewing your documentation](#writing-and-previewing-your-documentation)
|
||||
|
||||
## Prerequisities
|
||||
## Prerequisites
|
||||
|
||||
- A working Backstage instance with TechDocs installed (see
|
||||
[TechDocs getting started](getting-started.md))
|
||||
@@ -30,11 +30,6 @@ the documentation template.
|
||||
Create an entity from the documentation template and you will get the needed
|
||||
setup for free.
|
||||
|
||||
!!! warning Currently the Backstage Software Templates are limited to create
|
||||
repositories inside GitHub organizations. You also need to generate an personal
|
||||
access token and use as an environment variable. Read more about this
|
||||
[here](../software-templates/installation.md#runtime-dependencies).
|
||||
|
||||
### Manually add documentation setup to already existing repository
|
||||
|
||||
Prerequisities:
|
||||
@@ -81,12 +76,12 @@ updated documentation next time you run Backstage!
|
||||
## Writing and previewing your documentation
|
||||
|
||||
Using the `techdocs-cli` you can preview your docs inside a local Backstage
|
||||
instance and get automatic recompilation on changes. This is useful for when you
|
||||
want to write your documentation.
|
||||
instance and get live reload on changes. This is useful when you want to preview
|
||||
your documentation while writing.
|
||||
|
||||
To do this you can run:
|
||||
|
||||
```bash
|
||||
cd ~/<repository-path>/
|
||||
npx techdocs-cli serve
|
||||
cd /path/to/docs-repository/
|
||||
npx @techdocs/cli serve
|
||||
```
|
||||
|
||||
@@ -6,35 +6,8 @@ title: Getting Started
|
||||
TechDocs functions as a plugin to Backstage, so you will need to use Backstage
|
||||
to use TechDocs.
|
||||
|
||||
## What is Backstage?
|
||||
|
||||
Backstage is an open platform for building developer portals. It’s based on the
|
||||
developer portal we’ve been using internally at Spotify for over four years.
|
||||
[Read more here](https://github.com/spotify/backstage).
|
||||
|
||||
## Prerequisities
|
||||
|
||||
In order to use Backstage and TechDocs, you need to have the following
|
||||
installed:
|
||||
|
||||
- [Node.js](https://nodejs.org) Active LTS (long term support), currently v12
|
||||
- [Yarn](https://yarnpkg.com/getting-started/install)
|
||||
|
||||
## Creating a new Backstage app
|
||||
|
||||
> If you have already created a Backstage application, jump to
|
||||
> [Installing TechDocs](#installing-techdocs), otherwise complete this step.
|
||||
|
||||
To create a new Backstage application for TechDocs, run the following command:
|
||||
|
||||
```bash
|
||||
npx @backstage/create-app
|
||||
```
|
||||
|
||||
You will then be prompted to enter a name for your application. Once that's
|
||||
done, a new Backstage application will be created in a new folder. For example,
|
||||
if you choose the name `hello-world`, a new `hello-world` folder is created
|
||||
containing your new Backstage application.
|
||||
If you haven't setup Backstage already, start
|
||||
[here](../../getting-started/index.md).
|
||||
|
||||
## Installing TechDocs
|
||||
|
||||
@@ -74,17 +47,28 @@ export { plugin as TechDocs } from '@backstage/plugin-techdocs';
|
||||
### Setting the configuration
|
||||
|
||||
TechDocs allows for configuration of the docs storage URL through your
|
||||
`app-config` file.
|
||||
`app-config.yaml` file. We provide two different values to be configured,
|
||||
`requestUrl` and `storageUrl`. The `requestUrl` is what the reader will request
|
||||
its data from, and `storageUrl` is where the backend can find the stored
|
||||
documentation.
|
||||
|
||||
The default storage URL:
|
||||
The default storage and request URLs:
|
||||
|
||||
```yaml
|
||||
techdocs:
|
||||
storageUrl: http://localhost:7000/techdocs/static/docs
|
||||
requestUrl: http://localhost:7000/techdocs/docs
|
||||
```
|
||||
|
||||
If you want to configure this to point to another storage URL, change the value
|
||||
of `storageUrl`.
|
||||
If you want `techdocs-backend` to manage building and publishing, you want
|
||||
`requestUrl` to point to the default value (or wherever `techdocs-backend` is
|
||||
hosted). `storageUrl` should be where your publisher publishes your docs. Using
|
||||
the default `LocalPublish` that is the default value.
|
||||
|
||||
If you have a setup where you are not using `techdocs-backend` for managing
|
||||
building and publishing of your documentation, you want to change the
|
||||
`requestUrl` to point to your storage. In this case `storageUrl` is not
|
||||
required.
|
||||
|
||||
## Run Backstage locally
|
||||
|
||||
|
||||
@@ -3,4 +3,34 @@ id: configure-app-with-plugins
|
||||
title: Configuring App with plugins
|
||||
---
|
||||
|
||||
## Adding existing plugins to your app
|
||||
|
||||
Coming soon!
|
||||
|
||||
### Adding a plugin page to the Sidebar
|
||||
|
||||
In a standard Backstage app created with
|
||||
[@backstage/create-app](./create-an-app.md), the sidebar is managed inside
|
||||
`packages/app/src/sidebar.tsx`. The file exports the entire `Sidebar` element of
|
||||
your app, which you can extend with additional entries by adding new
|
||||
`SidebarItem` elements.
|
||||
|
||||
For example, if you install the `api-docs` plugin, a matching `SidebarItem`
|
||||
could be something like this:
|
||||
|
||||
```tsx
|
||||
// Import icon from MUI
|
||||
import ExtensionIcon from '@material-ui/icons/Extension';
|
||||
|
||||
// ... inside the AppSidebar component
|
||||
<SidebarItem icon={ExtensionIcon} to="api-docs" text="APIs" />;
|
||||
```
|
||||
|
||||
You can also use your own SVGs directly as icon components. Just make sure they
|
||||
are sized according to the Material UI's
|
||||
[SvgIcon](https://material-ui.com/api/svg-icon/) default of 24x24px, and set the
|
||||
extension to `.icon.svg`. For example:
|
||||
|
||||
```ts
|
||||
import InternalToolIcon from './internal-tool.icon.svg';
|
||||
```
|
||||
|
||||
@@ -15,7 +15,13 @@ To create a Backstage app, you will need to have
|
||||
[NodeJS](https://nodejs.org/en/download/) Active LTS Release installed
|
||||
(currently v12).
|
||||
|
||||
With `npx`:
|
||||
Backstage provides a utility for creating new apps. It guides you through the
|
||||
initial setup of selecting the name of the app and a database for the backend.
|
||||
The database options are either SQLite or PostgreSQL, where the latter requires
|
||||
you to set up a separate database instance. If in doubt, choose SQLite, but
|
||||
don't worry about the choice, it's easy to change later!
|
||||
|
||||
The easiest way to run the create app package is with `npx`:
|
||||
|
||||
```bash
|
||||
npx @backstage/create-app
|
||||
@@ -25,50 +31,45 @@ This will create a new Backstage App inside the current folder. The name of the
|
||||
app-folder is the name that was provided when prompted.
|
||||
|
||||
<p align='center'>
|
||||
<img src='https://github.com/spotify/backstage/raw/master/docs/getting-started/create-app_output.png' width='600' alt='create app'>
|
||||
<img src='../assets/getting-started/create-app_output.png' width='600' alt='create app'>
|
||||
</p>
|
||||
|
||||
Inside that directory, it will generate all the files and folder structure
|
||||
needed for you to run your app.
|
||||
|
||||
### Folder structure
|
||||
### General folder structure
|
||||
|
||||
Below is a simplified layout of the files and folders generated when creating an
|
||||
app.
|
||||
|
||||
```
|
||||
app
|
||||
├── README.md
|
||||
├── app-config.yaml
|
||||
├── lerna.json
|
||||
├── package.json
|
||||
├── prettier.config.js
|
||||
├── tsconfig.json
|
||||
├── packages
|
||||
│ └── app
|
||||
│ ├── package.json
|
||||
│ ├── tsconfig.json
|
||||
│ ├── public
|
||||
│ │ └── ...
|
||||
│ └── src
|
||||
│ ├── App.test.tsx
|
||||
│ ├── App.tsx
|
||||
│ ├── index.tsx
|
||||
│ ├── plugins.ts
|
||||
│ └── setupTests.ts
|
||||
└── plugins
|
||||
└── welcome
|
||||
├── README.md
|
||||
├── package.json
|
||||
├── tsconfig.json
|
||||
└── src
|
||||
├── index.ts
|
||||
├── plugin.test.ts
|
||||
├── plugin.ts
|
||||
├── setupTests.ts
|
||||
└── components
|
||||
├── Timer
|
||||
│ └── ...
|
||||
└── WelcomePage
|
||||
└── ...
|
||||
└── packages
|
||||
├── app
|
||||
└── backend
|
||||
```
|
||||
|
||||
- **app-config.yaml**: Main configuration file for the app. See
|
||||
[Configuration](https://backstage.io/docs/conf/) for more information.
|
||||
- **lerna.json**: Contains information about workspaces and other lerna
|
||||
configuration needed for the monorepo setup.
|
||||
- **package.json**: Root package.json for the project. _Note: Be sure that you
|
||||
don't add any npm dependencies here as they probably should be installed in
|
||||
the intended workspace rather than in the root._
|
||||
- **packages/**: Lerna leaf packages or "workspaces". Everything here is going
|
||||
to be a separate package, managed by lerna.
|
||||
- **packages/app/**: An fully functioning Backstage frontend app, that acts as a
|
||||
good starting point for you to get to know Backstage.
|
||||
- **packages/backend/**: We include a backend that helps power features such as
|
||||
[Authentication](https://backstage.io/docs/auth/),
|
||||
[Software Catalog](https://backstage.io/docs/features/software-catalog/software-catalog-overview),
|
||||
[Software Templates](https://backstage.io/docs/features/software-templates/software-templates-index)
|
||||
and [TechDocs](https://backstage.io/docs/features/techdocs/techdocs-overview)
|
||||
amongst other things.
|
||||
|
||||
## Run the app
|
||||
|
||||
When the installation is complete you can open the app folder and start the app.
|
||||
@@ -80,3 +81,13 @@ yarn start
|
||||
|
||||
_When `yarn start` is ready it should open up a browser window displaying your
|
||||
app, if not you can navigate to `http://localhost:3000`._
|
||||
|
||||
In most cases you will want to start the backend as well, as it is required for
|
||||
the catalog to work, along with many other plugins.
|
||||
|
||||
To start the backend, open a separate terminal session and run the following in
|
||||
the root directory:
|
||||
|
||||
```bash
|
||||
yarn workspace backend start
|
||||
```
|
||||
|
||||
@@ -1,84 +1,50 @@
|
||||
---
|
||||
id: index
|
||||
title: Running Backstage Locally
|
||||
title: Getting Started
|
||||
---
|
||||
|
||||
First make sure you are using NodeJS with an Active LTS Release, currently v12.
|
||||
This is made easy with a version manager such as nvm which allows for version
|
||||
switching.
|
||||
There are two different ways to get started with Backstage, either by creating a
|
||||
standalone app, or by cloning this repo. Which method you use depends on what
|
||||
you're planning to do.
|
||||
|
||||
Creating a standalone instance makes it simpler to customize the application for
|
||||
your needs whilst staying up to date with the project. You will also depend on
|
||||
`@backstage` packages from NPM, making the project much smaller. This is the
|
||||
recommended approach if you want to kick the tyres of Backstage or setup your
|
||||
own instance.
|
||||
|
||||
On the other hand, if you want to contribute plugins or to the project in
|
||||
general, it's easier to fork and clone this project. That will let you stay up
|
||||
to date with the latest changes, and gives you an easier path to make Pull
|
||||
Requests towards this repo.
|
||||
|
||||
### Creating a Standalone App
|
||||
|
||||
Backstage provides the `@backstage/create-app` package to scaffold standalone
|
||||
instances of Backstage. You will need to have
|
||||
[NodeJS](https://nodejs.org/en/download/) Active LTS Release installed
|
||||
(currently v12), and [yarn](https://classic.yarnpkg.com/en/docs/install). You
|
||||
will also need to have [Docker](https://docs.docker.com/engine/install/)
|
||||
installed to use some features like Software Templates and TechDocs.
|
||||
|
||||
Using `npx` you can then run the following to create an app in a chosen
|
||||
subdirectory of your current working directory:
|
||||
|
||||
```bash
|
||||
# Checking your version
|
||||
node --version
|
||||
> v14.7.0
|
||||
|
||||
# Adding a second node version
|
||||
nvm install 12
|
||||
> Downloading and installing node v12.18.3...
|
||||
> Now using node v12.18.3 (npm v6.14.6)
|
||||
npx @backstage/create-app
|
||||
```
|
||||
|
||||
To get up and running with a local Backstage to evaluate it, let's clone it off
|
||||
of GitHub and run an initial build.
|
||||
You will be taken through a wizard to create your app, and the output should
|
||||
look something like this. You can read more about this process
|
||||
[here](https://backstage.io/docs/getting-started/create-an-app).
|
||||
|
||||
```bash
|
||||
# Start from your local development folder
|
||||
git clone git@github.com:spotify/backstage.git
|
||||
cd backstage
|
||||
### Contributing to Backstage
|
||||
|
||||
# Fetch our dependencies and run an initial build
|
||||
yarn install
|
||||
yarn tsc
|
||||
yarn build
|
||||
```
|
||||
You can read more in our
|
||||
[CONTRIBUTING](https://github.com/spotify/backstage/blob/master/CONTRIBUTING.md)
|
||||
guide, which can help you get setup with a Backstage development environment.
|
||||
|
||||
Phew! Now you have a local repository that's ready to run and to add any open
|
||||
source contributions into.
|
||||
### Next steps
|
||||
|
||||
We are now going to launch two things: an example Backstage frontend app, and an
|
||||
example Backstage backend that the frontend talks to. You are going to need two
|
||||
terminal windows, both starting from the Backstage project root.
|
||||
|
||||
In the first window, run
|
||||
|
||||
```bash
|
||||
cd packages/backend
|
||||
yarn start
|
||||
```
|
||||
|
||||
That starts up a backend instance on port 7000.
|
||||
|
||||
In the other window, we will first populate the catalog with some nice mock data
|
||||
to look at, and then launch the frontend. These commands are run from the
|
||||
project root, not inside the backend directory.
|
||||
|
||||
```bash
|
||||
yarn lerna run mock-data
|
||||
yarn start
|
||||
```
|
||||
|
||||
That starts up the frontend on port 3000, and should automatically open a
|
||||
browser window showing it.
|
||||
|
||||
Congratulations! That should be it. Let us know how it went
|
||||
[on discord](https://discord.gg/EBHEGzX), file issues for any
|
||||
[feature](https://github.com/spotify/backstage/issues/new?labels=help+wanted&template=feature_template.md)
|
||||
or
|
||||
[plugin suggestions](https://github.com/spotify/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME),
|
||||
or
|
||||
[bugs](https://github.com/spotify/backstage/issues/new?labels=bug&template=bug_template.md)
|
||||
you have, and feel free to
|
||||
[contribute](https://github.com/spotify/backstage/blob/master/CONTRIBUTING.md)!
|
||||
|
||||
## Creating a Plugin
|
||||
|
||||
The value of Backstage grows with every new plugin that gets added. Here is a
|
||||
collection of tutorials that will guide you through setting up and extending an
|
||||
instance of Backstage with your own plugins.
|
||||
|
||||
- [Development Environment](development-environment.md)
|
||||
- [Create a Backstage Plugin](../plugins/create-a-plugin.md)
|
||||
- [Structure of a Plugin](../plugins/structure-of-a-plugin.md)
|
||||
- [Utility APIs](../api/utility-apis.md)
|
||||
|
||||
[Back to Docs](../README.md)
|
||||
Take a look at the [Running Backstage Locally](./running-backstage-locally.md)
|
||||
guide to learn how to set up Backstage, and how to develop on the platform.
|
||||
|
||||
@@ -0,0 +1,109 @@
|
||||
---
|
||||
id: running-backstage-locally
|
||||
title: Running Backstage Locally
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Node.js
|
||||
|
||||
First make sure you are using NodeJS with an Active LTS Release, currently v12.
|
||||
This is made easy with a version manager such as
|
||||
[nvm](https://github.com/nvm-sh/nvm) which allows for version switching.
|
||||
|
||||
```bash
|
||||
# Installing a new version
|
||||
nvm install 12
|
||||
> Downloading and installing node v12.18.3...
|
||||
> Now using node v12.18.3 (npm v6.14.6)
|
||||
|
||||
# Checking your version
|
||||
node --version
|
||||
> v12.18.3
|
||||
```
|
||||
|
||||
- yarn
|
||||
|
||||
Please refer to the
|
||||
[installation instructions for yarn](https://classic.yarnpkg.com/en/docs/install/).
|
||||
|
||||
- Docker
|
||||
|
||||
We use Docker for few of our core features. So, you will need Docker installed
|
||||
locally to use features like Software Templates and TechDocs. Please refer to
|
||||
the
|
||||
[installation instructions for Docker](https://docs.docker.com/engine/install/).
|
||||
|
||||
## Clone and Build
|
||||
|
||||
To get up and running with a local Backstage to evaluate it, let's clone it off
|
||||
of GitHub and run an initial build.
|
||||
|
||||
```bash
|
||||
# Start from your local development folder
|
||||
git clone git@github.com:spotify/backstage.git
|
||||
cd backstage
|
||||
|
||||
# Fetch our dependencies and run an initial build
|
||||
yarn install
|
||||
yarn tsc
|
||||
yarn build
|
||||
```
|
||||
|
||||
Phew! Now you have a local repository that's ready to run and to add any open
|
||||
source contributions into.
|
||||
|
||||
We are now going to launch two things: an example Backstage frontend app, and an
|
||||
example Backstage backend that the frontend talks to. You are going to need two
|
||||
terminal windows, both starting from the Backstage project root.
|
||||
|
||||
In the first window, run
|
||||
|
||||
```bash
|
||||
cd packages/backend
|
||||
yarn start
|
||||
```
|
||||
|
||||
That starts up a backend instance on port 7000.
|
||||
|
||||
In the other window, we will then launch the frontend. This command is run from
|
||||
the project root, not inside the backend directory.
|
||||
|
||||
```bash
|
||||
yarn start
|
||||
```
|
||||
|
||||
That starts up the frontend on port 3000, and should automatically open a
|
||||
browser window showing it.
|
||||
|
||||
## Authentication
|
||||
|
||||
When Backstage starts, you can choose to enter as a Guest user and start
|
||||
exploring.
|
||||
|
||||
But you can also set up any of the available authentication methods. The easiest
|
||||
option will be GitHub. To setup GitHub authentication in Backstage, see
|
||||
[these instructions](https://github.com/spotify/backstage/tree/master/plugins/auth-backend#github).
|
||||
|
||||
---
|
||||
|
||||
Congratulations! That should be it. Let us know how it went
|
||||
[on discord](https://discord.gg/EBHEGzX), file issues for any
|
||||
[feature](https://github.com/spotify/backstage/issues/new?labels=help+wanted&template=feature_template.md)
|
||||
or
|
||||
[plugin suggestions](https://github.com/spotify/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME),
|
||||
or
|
||||
[bugs](https://github.com/spotify/backstage/issues/new?labels=bug&template=bug_template.md)
|
||||
you have, and feel free to
|
||||
[contribute](https://github.com/spotify/backstage/blob/master/CONTRIBUTING.md)!
|
||||
|
||||
## Creating a Plugin
|
||||
|
||||
The value of Backstage grows with every new plugin that gets added. Here is a
|
||||
collection of tutorials that will guide you through setting up and extending an
|
||||
instance of Backstage with your own plugins.
|
||||
|
||||
- [Development Environment](development-environment.md)
|
||||
- [Create a Backstage Plugin](../plugins/create-a-plugin.md)
|
||||
- [Structure of a Plugin](../plugins/structure-of-a-plugin.md)
|
||||
- [Utility APIs](../api/utility-apis.md)
|
||||
@@ -0,0 +1,41 @@
|
||||
---
|
||||
id: logos
|
||||
title: Logos
|
||||
sidebar_label: Logo assets
|
||||
---
|
||||
|
||||
Guidelines for how to use the Backstage logo and icon can be found
|
||||
[here](/logo_assets/Backstage_Identity_Assets_Overview.pdf). The assets below
|
||||
are all in `.svg` format. Other formats are available in the
|
||||
[repository](https://github.com/spotify/backstage/tree/master/microsite/static/logo_assets).
|
||||
|
||||
## Backstage logo
|
||||
|
||||
<a href="/logo_assets/svg/Logo_White.svg">
|
||||
<img src="/logo_assets/svg/Logo_White.svg" width="600" />
|
||||
</a>
|
||||
|
||||
<a href="/logo_assets/svg/Logo_Teal.svg">
|
||||
<img src="/logo_assets/svg/Logo_Teal.svg" width="600" />
|
||||
</a>
|
||||
|
||||
<a href="/logo_assets/svg/Logo_Black.svg">
|
||||
<img src="/logo_assets/svg/Logo_Black.svg" width="600" style="background-color:white" />
|
||||
</a>
|
||||
|
||||
## Backstage icon
|
||||
|
||||
<div>
|
||||
<a href="/logo_assets/svg/Icon_White.svg">
|
||||
<img src="/logo_assets/svg/Icon_White.svg" width="180" height="180" />
|
||||
</a>
|
||||
<a href="/logo_assets/svg/Icon_Teal.svg">
|
||||
<img src="/logo_assets/svg/Icon_Teal.svg" width="180" height="180" />
|
||||
</a>
|
||||
<a href="/logo_assets/svg/Icon_Gradient.svg">
|
||||
<img src="/logo_assets/svg/Icon_Gradient.svg" width="180" height="180" />
|
||||
</a>
|
||||
<a href="/logo_assets/svg/Icon_Black.svg">
|
||||
<img src="/logo_assets/svg/Icon_Black.svg" width="180" height="180" style="background-color:white" />
|
||||
</a>
|
||||
</div>
|
||||
@@ -52,7 +52,10 @@ configuration will lead to the proxy acting on backend requests to
|
||||
|
||||
The value inside each route is either a simple URL string, or an object on the
|
||||
format accepted by
|
||||
[http-proxy-middleware](https://www.npmjs.com/package/http-proxy-middleware).
|
||||
[http-proxy-middleware](https://www.npmjs.com/package/http-proxy-middleware). It
|
||||
is also possible to limit the forwarded HTTP methods with the configuration
|
||||
`allowedMethods`, for example `allowedMethods: ['GET']` to enforce read-only
|
||||
access.
|
||||
|
||||
If the value is a string, it is assumed to correspond to:
|
||||
|
||||
|
||||
@@ -53,6 +53,11 @@ async function verifyUrl(basePath, url) {
|
||||
return { url, basePath, problem: 'not-relative' };
|
||||
}
|
||||
|
||||
const staticPath = resolvePath(projectRoot, 'microsite/static', `.${url}`);
|
||||
if (await fs.pathExists(staticPath)) {
|
||||
return;
|
||||
}
|
||||
|
||||
path = resolvePath(projectRoot, `.${url}`);
|
||||
} else {
|
||||
path = resolvePath(dirname(resolvePath(projectRoot, basePath)), url);
|
||||
@@ -103,7 +108,9 @@ async function main() {
|
||||
console.log(`Found ${badUrls.length} bad links within repo`);
|
||||
for (const { url, basePath, problem } of badUrls) {
|
||||
if (problem === 'missing') {
|
||||
console.error(`Unable to reach ${url}, linked from ${basePath}`);
|
||||
console.error(
|
||||
`Unable to reach ${url} from root or microsite/static/, linked from ${basePath}`,
|
||||
);
|
||||
} else if (problem === 'not-relative') {
|
||||
console.error('Links to /docs/ must be relative');
|
||||
console.error(` From: ${basePath}`);
|
||||
|
||||
Reference in New Issue
Block a user