This document takes you through setting up a backstage app that runs in your own environment. It starts with a skeleton install and verifying of the monorepo's functionality. Next, GitHub authentication is added and tested.
This document assumes you have NodeJS 12 active along with Yarn. Please note, that at the time of this writing, the current version is 0.1.1-alpha.21. This guide can still be used with future versions, just, verify as you go. If you run into issues, you can compare your setup with mine here > simple-backstage-app.
From the terminal:
npx @backstage/create-app
id
for your new app like mybiz-backstage
I went with
simple-backstage-app
SQLite
as your database. This is the quickest way to get started as
PostgreSQL requires additional setup not covered here.yarn --cwd packages/backend start
# You should see positive verbiage in your terminal output
2020-09-11T22:20:26.712Z backstage info Listening on :7000
yarn start
# You should see positive verbiage in your terminal output
ℹ 「wds」: Project is running at http://localhost:3000/
Once the app compiles, a browser window should have popped with your stand alone
application loaded at localhost:3000
. This could take a couple minutes.
# You should see positive verbiage in your terminal output
ℹ 「wdm」: Compiled successfully.
Since there is no auth currently configured, you are automatically entered as a guest. Let's fix that now and add auth.
app-config.yaml
and change it as followsfrom:
auth:
providers: {}
to:
auth:
providers:
github:
development:
clientId:
$secret:
env: AUTH_GITHUB_CLIENT_ID
clientSecret:
$secret:
env: AUTH_GITHUB_CLIENT_SECRET
## uncomment the following three lines if using enterprise
# enterpriseInstanceUrl:
# $secret:
# env: AUTH_GITHUB_ENTERPRISE_INSTANCE_URL
The yaml file above will look for auth values from environment variables. I've stuffed mine into my startup profile.
```zsh # Pass values on the command line when starting the backend. Not my favorite. Too much typing. AUTH_GITHUB_CLIENT_ID=xxx AUTH_GITHUB_CLIENT_SECRET=xxx yarn --cwd packages/backend start ```
# On a macOS Catalina with Z Shell
# ------ simple-backstage-app GitHub
export AUTH_GITHUB_CLIENT_ID=xxx
export AUTH_GITHUB_CLIENT_SECRET=xxx
## uncomment if using enterprise
# export AUTH_GITHUB_ENTERPRISE_INSTANCE_URL=https://github.{MY_BIZ}.com
# Loading the new variables
% source ~/.zshrc
# Any other currently opened terminals need to be restarted to pick up the new values
# verify your setup by running env
% env
# should output something like
> ...
> AUTH_GITHUB_CLIENT_ID=someClientId
> AUTH_GITHUB_CLIENT_SECRET=someClientSecret
> ...
App.tsx
as follows// Add the following imports to the existing list from core
import { githubAuthApiRef, SignInPage } from '@backstage/core';
const app = createApp({
apis,
plugins: Object.values(plugins),
components: {
SignInPage: props => {
return (
<SignInPage
{...props}
providers={[
{
id: 'github-auth-provider',
title: 'GitHub',
message: 'Simple Backstage Application Login',
apiRef: githubAuthApiRef,
},
]}
align="center"
/>
);
},
},
});
apis.ts
as follows// Add the following imports to the existing list from core
import { githubAuthApiRef, GithubAuth } from '@backstage/core';
from:
builder.add(oauthRequestApiRef, new OAuthRequestManager());
to:
const oauthRequestApi = builder.add(
oauthRequestApiRef,
new OAuthRequestManager(),
);
builder.add(
githubAuthApiRef,
GithubAuth.create({
discoveryApi,
oauthRequestApi,
}),
);
Start the backend and frontend as before. When the browser loads, you should be presented with a login page for GitHub. Login as usual with your GitHub account. If this is your first time, you will be asked to authorize and then are redirected to the catalog page if all is well.
We modified three files. Starting with app-config.yml by adding in GitHub as a provider. Then apis.ts where we registered GithubAuth as usable API. We then modified App.tsx where we included the SignInPage with a single provider for our GitHub configuration.
You're probably eager to write your first custom plugin. Follow this next tutorial for an in-depth look at a custom GitHub repository browser plugin. TODO.