Getting started with Portal for Backstage

Deploying Portal to a production environment

This guide highlights what to keep in mind when deploying Portal to an production environment.

Note: For those looking to explore Portal without deploying to production, you can run Portal locally. Read more here. Please be aware that any modifications made in the local instance of Portal cannot be transferred to your production environment.

Prerequisites

Before deploying Portal, you'll need to verify you can connect to backstage-api.spotify.com which is essential for the operation of Portal:

nc -vz backstage-api.spotify.com 443
Connection to backstage-api.spotify.com 443 port [tcp/https] succeeded!

If the connection test fails, follow these troubleshooting steps:

• Check Firewall Settings: Ensure that no firewall is blocking access to port 443, which is used for HTTPS traffic.

• Verify Network Configuration:

  • Confirm that your network settings, including proxies and VPNs, allow connections to external HTTPS services.
  • Use tools like ping and traceroute to diagnose connectivity issues.

• Consult Network Logs: Check network logs for any blocked attempts or outgoing requests to identify if any additional configurations are necessary.

• Contact Support: If you continue to experience issues, consider contacting your IT support team for help with network settings.

Kubernetes

1. Generate a secure password to be used to setup Portal for the first time

   The password used by the root user is supplied using the PORTAL_ROOT_USER_PASSWORD environment variable.

   Signing in as the root user is automatically disabled upon completion of setting up an authentication provider, however it's recommended to have a strong password here.

2. Generate secrets used for config encryption and backend authentication for the Soundcheck plugin

   As documented here Portal requires a certain number of environment variables to be defined for it to successfully start.

   The signing key for encrypting Portal's database content is supplied using the PORTAL_CONFIG_ENCRYPTION_KEY environment variable. It is required to be exactly 32 characters long.

   It can be generated like this:

   node -p 'require("crypto").randomBytes(32).toString("hex").substring(0,32)'

   The signing key for Souncheck backend's auth is supplied using the PORTAL_SECRET_BACKEND_KEY environment variable. The key can be any base64 encoded secret and generated like this:

   node -p 'require("crypto").randomBytes(24).toString("base64")'

3. Create a deployment

   Use this Kubernetes Deployment descriptor template and make sure the <value> fields are substituted with real values.

   Read more about secrets and environment variables here

   # backstage-portal.yaml
   
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: backstage-portal
     namespace: backstage-portal
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: backstage-portal
     template:
       metadata:
         labels:
           app: backstage-portal
       spec:
         containers:
           # Portal for Backstage
           - name: backstage-portal
             image: spotify/portal:<version>
             imagePullPolicy: IfNotPresent
             env:
               - name: PORTAL_BASE_URL
                 value: <base-url>
               - name: PORTAL_SECRET_BACKEND_KEY
                 value: <backend-key>
               - name: PORTAL_DATABASE_HOST
                 value: localhost
               - name: PORTAL_DATABASE_PORT
                 value: '5432'
               - name: PORTAL_DATABASE_USER
                 value: <postgres-user>
               - name: PORTAL_SECRET_DATABASE_PASSWORD
                 value: <postgres-password>
               - name: PORTAL_CONFIG_ENCRYPTION_KEY
                 value: <encryption-key>
               - name: PORTAL_ROOT_USER_PASSWORD
                 value: <root-password>
             ports:
               - name: http
                 containerPort: 7007
                 protocol: TCP
           # Postgres database sidecar
           - name: database
             image: postgres:13
             env:
               - name: POSTGRES_USER
                 value: <postgres-user>
               - name: POSTGRES_PASSWORD
                 value: <postgres-password>
               - name: POSTGRES_DB
                 value: <postgres-database>
             ports:
               - name: postgres
                 containerPort: 5432
                 protocol: TCP

4. Applying that Deployment to a Kubernetes cluster 🎉

   kubectl apply -f backstage-portal.yaml

Continue with the official documentation on how to learn more about deploying to Kubernetes.

System Requirements for Running Portal

To ensure Portal runs reliably, we provide both minimum and recommended system configurations:

Minimum Requirements

• CPU: At least 1 CPU core.
• Memory: At least 2 GB of RAM.

Recommended Configuration

• CPU: 2 CPU cores.
• Memory: 4 GB of RAM.

These specifications are designed to support the basic operations of Portal. For environments expecting higher traffic, consider scaling these resources to meet increased demands.

External Connectivity

Telemetry

Portal collects limited telemetry for product improvement purposes on an opt-in basis. If you've opted-in, the Portal backend will attempt to connect to https://www.google-analytics.com to send telemetry data.

Obtaining a License Key

To use Portal, you must obtain a license key.

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.