Getting started with Portal for Backstage

Setup Wizard

The first time Portal is started, a Wizard is presented that will assist in setting up authentication and determining at least one authorized user.

Choose a sign-in provider

Provide credentials

How to find your personal access token

Personal access tokens are alternative to using passwords for authentication to GitHub.

You can create a personal access token in Settings > Developer settings on GitHub. Make sure the following scopes are selected: read:user, read:org, user:email and repo

How to find your Client ID and Secret

If you have previously registered an OAuth app, you can find your Client ID by visiting your app in the developer settings. If you can't find your Client Secret you can generate a new one and copy it over.

If you haven't previously registered an OAuth app in GitHub, you will need to create it under your GitHub organization under developer settings. Once your app is registered, a Client ID and Secret will be generated. Copy and store your secret somewhere safely as you won't be able to see it again later.

Note: When creating your OAuth app, use the Homepage URL and Authorization callback URL displayed in the in-app documentation to the right.

Add organizations and administrators

Note: A user matching the auth providers username is automatically identified and added as an administrator.

Submit

Once completed Portal is ready!

Setup Guide

Once the Setup Wizard is complete, you can access the Setup Guide: this offers a detailed checklist of essential plugins to optimize your Portal experience, complete with links to additional guides, support resources, and FAQs.

Personalization

When signed in to Portal as an authorized user, the Config Manager is available.

The Config Manager provides a UI for viewing and updating Portal configuration. It retrieves and updates the configuration stored in Portal using an encrypted PostgreSQL database.

Configuration schemas are automatically detected when the Config Manager loads and then grouped by related plugins into one general configuration page for all similar settings.

In other words, the Auth configuration page may consist of multiple auth related plugins, such as @backstage/plugin-auth-backend, @backstage/plugin-auth-backend-module-google-provider, @backstage/plugin-auth-backend-module-gcp-iap-provider etc.

View and edit configuration

To view or edit configuration for a given plugin simply click the "View" button next to the plugin group name on the overview page.

Each configuration page consists of an automatically generated web form based on the combined schemas as mentioned above. The form automatically renders an appropriate input type based on the type of the field in the schema.

Note: A few specific configuration fields will not be possible to edit. They are marked as read-only by Portal to prevent severe mis-configurations from happening.

Update Company Name

After deploying Portal, one of the first configuration changes you should consider is updating the organization name. This will change the "My Company Catalog" heading on the catalog index page and the page title in your browser tab.

To make this update, navigate to the "App" plugin under "Core plugins" in the Config Manager and click on the "View" button. Locate the "organization" section, and enter your company's name in the "name" input field.

Confirm your update by clicking "Save Changes". Your Portal instance will now display your company name on the catalog index page. 🎉

Add More Authorized Users in Config Manager

Config Manager is integrated with the permission framework and is only accessible by authorized users.

To add a user or group to the list of authorized users, navigate to the "Portal" configuration page on the Config Manager overview page.

Then click the "Add Item" button within the "Authorized Users" section and fill in the entity reference of the user or group that should be added.

Confirm the addition by clicking "Save Changes."

Starting and stopping plugins

Most plugins can be enabled or disabled within Portal using a button in the top right.

Stopping a plugin will remove the functionality related to the plugin from Portal. That includes both frontend and backend features.

A plugin that is stopped will appear as "Not running" on the overview page.

To start the plugin again, click "Start Plugin"

Finding configuration

Locating configuration is made easy in Portal using the search box in the Config Manager overview page. Enter the name or dot notation path (e.g. organization.name) of the configuration then click on a result to be taken directly to the configuration within the plugin.

Onboarding your team

Portal and the Portal Software Catalog make it easy for one team to manage 10 services — and makes it possible for your company to manage thousands of them.

Learn more about onboarding teams in the Software Catalog Overview.