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
You have the choice to enable GitHub integration through two methods:
We recommend using a GitHub App as this provides more granular control over permissions and scope while reducing the risk of orphaned or compromised credentials.
Create a GitHub App
In your GitHub organization navigate to settings -> Developer settings -> GitHub Apps and click on New GitHub App.
Fill in the following information:
GitHub App name:<organizaion> PortalHomepage URL:https://<organization>.spotifyportal.comCallback URL:https://<organization>.spotifyportal.com/api/auth/github/handler/frame
Deselect Active under the Webhook section. Set the following permissions for the app:
Repository permissions:
| Permission | Access Level |
|---|---|
| Administration | Read / Write |
| Actions | Read / Write |
| Code scanning alerts | Read |
| Commit statuses | Read |
| Contents | Read / Write |
| Dependabot alerts | Read |
| Issues | Read / Write |
| Metadata | Read |
| Pull requests | Read / Write |
| Repository security advisories | Read |
| Secret scanning alerts | Read |
Organization permissions:
| Permission | Access Level |
|---|---|
| Members | Read |
Lastly, click on Create GitHub App.
Next, navigate to the newly created GitHub App and click on Generate a new client secret,
then input this value into the setup wizard. Additionally, scroll down and click on Generate a private key,
then input the private key into the setup wizard.
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: When using a personal access token, 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 (/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-onlyby 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.