docs: start adding user roles to getting started documentation
Following CNCF guidelines for improved Backstage documentation. Signed-off-by: Aramis <sennyeyaramis@gmail.com>
This commit is contained in:
Aramis
@@ -0,0 +1,134 @@
|
||||
---
|
||||
id: authentication
|
||||
title: Authentication
|
||||
description: How to set up authentication into your Backstage installation
|
||||
---
|
||||
|
||||
Audience: Admins or Developers
|
||||
|
||||
### Setting up authentication
|
||||
|
||||
There are multiple authentication providers available for you to use with
|
||||
Backstage, feel free to follow
|
||||
[the instructions for adding authentication](../../auth/index.md).
|
||||
|
||||
For this tutorial we choose to use GitHub, a free service most of you might be
|
||||
familiar with. For other options, see
|
||||
[the auth provider documentation](../../auth/github/provider.md#create-an-oauth-app-on-github).
|
||||
|
||||
Go to
|
||||
[https://github.com/settings/applications/new](https://github.com/settings/applications/new)
|
||||
to create your OAuth App. The `Homepage URL` should point to Backstage's
|
||||
frontend, in our tutorial it would be `http://localhost:3000`. The
|
||||
`Authorization callback URL` will point to the auth backend, which will most
|
||||
likely be `http://localhost:7007/api/auth/github/handler/frame`.
|
||||
|
||||
|
||||
|
||||
Take note of the `Client ID` and the `Client Secret`. Open `app-config.yaml`,
|
||||
and add your `clientId` and `clientSecret` to this file. It should end up
|
||||
looking like this:
|
||||
|
||||
```yaml title="app-config.yaml"
|
||||
auth:
|
||||
# see https://backstage.io/docs/auth/ to learn about auth providers
|
||||
environment: development
|
||||
providers:
|
||||
github:
|
||||
development:
|
||||
clientId: YOUR CLIENT ID
|
||||
clientSecret: YOUR CLIENT SECRET
|
||||
```
|
||||
|
||||
### Add sign-in option to the frontend
|
||||
|
||||
Backstage will re-read the configuration. If there's no errors, that's great! We
|
||||
can continue with the last part of the configuration. The next step is needed to
|
||||
change the sign-in page, this you actually need to add in the source code.
|
||||
|
||||
Open `packages/app/src/App.tsx` and below the last `import` line, add:
|
||||
|
||||
```typescript title="packages/app/src/App.tsx"
|
||||
import { githubAuthApiRef } from '@backstage/core-plugin-api';
|
||||
import { SignInPage } from '@backstage/core-components';
|
||||
```
|
||||
|
||||
Search for `const app = createApp({` in this file, and below `apis,` add:
|
||||
|
||||
```tsx title="packages/app/src/App.tsx"
|
||||
components: {
|
||||
SignInPage: props => (
|
||||
<SignInPage
|
||||
{...props}
|
||||
auto
|
||||
provider={{
|
||||
id: 'github-auth-provider',
|
||||
title: 'GitHub',
|
||||
message: 'Sign in using GitHub',
|
||||
apiRef: githubAuthApiRef,
|
||||
}}
|
||||
/>
|
||||
),
|
||||
},
|
||||
```
|
||||
|
||||
> Note: The default Backstage app comes with a guest Sign In Resolver. This resolver makes all users share a single "guest" identity and is only intended as a minimum requirement to quickly get up and running. You can read more about how [Sign In Resolvers](../../auth/identity-resolver.md#sign-in-resolvers) play a role in creating a [Backstage User Identity](../../auth/identity-resolver.md#backstage-user-identity) for logged in users.
|
||||
|
||||
Restart Backstage from the terminal, by stopping it with `Control-C`, and starting it with `yarn dev` . You should be welcomed by a login prompt!
|
||||
|
||||
> Note: Sometimes the frontend starts before the backend resulting in errors on the sign in page. Wait for the backend to start and then reload Backstage to proceed.
|
||||
|
||||
To learn more about Authentication in Backstage, here are some docs you
|
||||
could read:
|
||||
|
||||
- [Authentication in Backstage](../../auth/index.md)
|
||||
- [Using organizational data from GitHub](../../integrations/github/org.md)
|
||||
|
||||
### Setting up a GitHub Integration
|
||||
|
||||
The GitHub integration supports loading catalog entities from GitHub or GitHub
|
||||
Enterprise. Entities can be added to static catalog configuration, registered
|
||||
with the catalog-import plugin, or discovered from a GitHub organization. Users
|
||||
and Groups can also be loaded from an organization. While using [GitHub Apps](../../integrations/github/github-apps.md)
|
||||
might be the best way to set up integrations, for this tutorial you'll use a
|
||||
Personal Access Token.
|
||||
|
||||
Create your Personal Access Token by opening
|
||||
[the GitHub token creation page](https://github.com/settings/tokens/new). Use a
|
||||
name to identify this token and put it in the notes field. Choose a number of
|
||||
days for expiration. If you have a hard time picking a number, we suggest to go
|
||||
for 7 days, it's a lucky number.
|
||||
|
||||
|
||||
|
||||
Set the scope to your likings. For this tutorial, selecting `repo` and `workflow` is required as the scaffolding job in this guide configures a GitHub actions workflow for the newly created project.
|
||||
|
||||
For this tutorial, we will be writing the token to `app-config.local.yaml`. This file might not exist for you, so if it doesn't go ahead and create it alongside the `app-config.yaml` at the root of the project.
|
||||
This file should also be excluded in `.gitignore`, to avoid accidental committing of this file.
|
||||
|
||||
In your `app-config.local.yaml` go ahead and add the following:
|
||||
|
||||
```yaml title="app-config.local.yaml"
|
||||
integrations:
|
||||
github:
|
||||
- host: github.com
|
||||
token: ghp_urtokendeinfewinfiwebfweb # this should be the token from GitHub
|
||||
```
|
||||
|
||||
That's settled. This information will be leveraged by other plugins.
|
||||
|
||||
If you're looking for a more production way to manage this secret, then you can do the following with the token being stored in an environment variable called `GITHUB_TOKEN`.
|
||||
|
||||
```yaml title="app-config.local.yaml"
|
||||
integrations:
|
||||
github:
|
||||
- host: github.com
|
||||
token: ${GITHUB_TOKEN} # this will use the environment variable GITHUB_TOKEN
|
||||
```
|
||||
|
||||
> Note: If you've updated the configuration for your integration, it's likely that the backend will need a restart to apply these changes. To do this, stop the running instance in your terminal with `Control-C`, then start it again with `yarn dev`. Once the backend has restarted, retry the operation.
|
||||
|
||||
Some helpful links, for if you want to learn more about:
|
||||
|
||||
- [Other available integrations](../../integrations/index.md)
|
||||
- [Using GitHub Apps instead of a Personal Access Token](../../integrations/github/github-apps.md#docsNav)
|
||||
@@ -0,0 +1,139 @@
|
||||
---
|
||||
id: database
|
||||
title: Database
|
||||
description: How to set up PostgreSQL for your Backstage instance.
|
||||
---
|
||||
|
||||
Audience: Admins
|
||||
|
||||
### Summary
|
||||
|
||||
This guide walks through how to set up a PostgreSQL database to host your Backstage data. It assumes you've already have a scaffolded Backstage app from following the [Standalone Install](../standalone-install.md) guide.
|
||||
|
||||
By the end of this tutorial, you will have a working PostgreSQL database hooked up to your Backstage install.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
This guide assumes a basic understanding of working on a Linux based operating system and have some experience with the terminal, specifically, these commands: `apt-get`, `psql`, `yarn`.
|
||||
|
||||
- Access to a Linux-based operating system, such as Linux, MacOS or
|
||||
[Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/)
|
||||
- An account with elevated rights to install prerequisites on your operating
|
||||
system
|
||||
- If the database is not hosted on the same server as the Backstage app, the
|
||||
PostgreSQL port needs to be accessible (the default is `5432` or `5433`)
|
||||
|
||||
### 1. Install and configure PostgreSQL
|
||||
|
||||
:::tip Already configured your database?
|
||||
|
||||
If you've already installed PostgreSQL and created a schema and user, you can skip to [Step 2](#2-configuring-backstage-pg-client).
|
||||
|
||||
:::
|
||||
|
||||
Let's install PostgreSQL and get it set up for our Backstage app. First, we'll need to actually install the SQL server.
|
||||
|
||||
:::caution
|
||||
|
||||
The command below is for Linux. If you're not on Linux or having issues with package managers, check out [how to install PostgreSQL](https://www.postgresql.org/download/) to help you get sorted.
|
||||
|
||||
:::
|
||||
|
||||
```shell
|
||||
sudo apt-get install postgresql
|
||||
```
|
||||
|
||||
To test if your database is working:
|
||||
|
||||
```shell
|
||||
sudo -u postgres psql
|
||||
```
|
||||
|
||||
You should see a very welcoming message, like:
|
||||
|
||||
```shell
|
||||
psql (12.9 (Ubuntu 12.9-0ubuntu0.20.04.1))
|
||||
Type "help" for help.
|
||||
|
||||
postgres=#
|
||||
```
|
||||
|
||||
For this tutorial we're going to use the existing postgres user. The next step is to set the password for this user. You'll want to replace the `<secret>` with a real password in the command below. Keep note of the password you choose here, you'll need it later.
|
||||
|
||||
```shell
|
||||
postgres=# ALTER USER postgres PASSWORD '<secret>';
|
||||
```
|
||||
|
||||
That's enough database administration to get started. Type `\q`, followed by
|
||||
pressing the enter key. Then again type `exit` and press enter. Next, you need
|
||||
to install and configure the client.
|
||||
|
||||
### 2. Configuring Backstage `pg` Client
|
||||
|
||||
Go to the root directory of your freshly installed Backstage
|
||||
App. Run the following to install the PostgreSQL client into your backend:
|
||||
|
||||
```bash
|
||||
# From your Backstage root directory
|
||||
yarn add --cwd packages/backend pg
|
||||
```
|
||||
|
||||
Use your favorite editor to open `app-config.yaml` and add your PostgreSQL
|
||||
configuration in the root directory of your Backstage app using the credentials from the previous steps.
|
||||
|
||||
```yaml title="app-config.yaml"
|
||||
backend:
|
||||
database:
|
||||
# highlight-remove-start
|
||||
client: better-sqlite3
|
||||
connection: ':memory:'
|
||||
# highlight-remove-end
|
||||
# highlight-add-start
|
||||
# config options: https://node-postgres.com/apis/client
|
||||
client: pg
|
||||
connection:
|
||||
host: ${POSTGRES_HOST}
|
||||
port: ${POSTGRES_PORT}
|
||||
user: ${POSTGRES_USER}
|
||||
password: ${POSTGRES_PASSWORD}
|
||||
# highlight-add-end
|
||||
```
|
||||
|
||||
The `${...}` syntax denotes environment variables, specifically,
|
||||
|
||||
1. `POSTGRES_HOST` - The URL/IP to access your PostgreSQL database at. If you've installed PostgreSQL locally, this will likely be 127.0.0.1.
|
||||
2. `POSTGRES_PORT` - The port to access your PostgreSQL database on. If you've installed PostgreSQL locally, this will be `5432` or `5433`.
|
||||
3. `POSTGRES_USER` - The user from the SQL command above, `postgres`.
|
||||
4. `POSTGRES_PASSWORD` - The password you set in the SQL command above.
|
||||
|
||||
When filling these out, you have 2 choices,
|
||||
|
||||
1. Use environment variables when you launch Backstage, either using an environment variable injector like [`dotenv-cli`](https://www.npmjs.com/package/dotenv-cli) or [`env-cmd`](https://www.npmjs.com/package/env-cmd) or loading the variables directly with `EXPORT POSTGRES_...=...`.
|
||||
2. Replacing the entire `${POSTGRES_...}` string with the value you identified earlier. This is the less secure option, but worth doing if you don't have much experience with environment variables.
|
||||
|
||||
:::danger
|
||||
|
||||
If you opt for the second option of replacing the entire string, take care to not commit your `app-config.yaml` to source control. It may contain passwords that you don't want leaked.
|
||||
|
||||
:::
|
||||
|
||||
[Start the Backstage app](../standalone-install.md#2-run-the-backstage-app):
|
||||
|
||||
```shell
|
||||
yarn dev
|
||||
```
|
||||
|
||||
After the Backstage frontend launches, you should notice that nothing has changed. This is a good sign. If everything is setup correctly above, this means that the data is flowing from the demo data files directly into your database!
|
||||
|
||||
We've now made your data persist in your Backstage database.
|
||||
|
||||
## Next Steps
|
||||
|
||||
We recommend you read [Setting up authentication](./authentication.md) next.
|
||||
|
||||
## Further Reading
|
||||
|
||||
If you want to read more about the database configuration, here are some helpful links:
|
||||
|
||||
- [Configuring Plugin Databases](../tutorials/configuring-plugin-databases.md#privileges)
|
||||
- [Read more about Knex](http://knexjs.org/), the database wrapper that we use.
|
||||
Reference in New Issue
Block a user