Backstage Integration Admin Guide

ADMIN PRIVILEGES REQUIRED

Overview

Backstage.io is a developer portal that streamlines software development by providing developers a common repository of code, libraries, documentation, and other resources. You can connect Backstage to your Stack Internal Basic, Business, or Enterprise site to display questions, tags, and users, as well as ask questions from your Backstage application.

With this Backstage integration, you can unlock your team's collective intelligence directly within backstage. Seamlessly integrate with Stack Overflow Internal to provide developers with instant access to your organization's knowledge hub. Empower them to find answers faster with:

• Centralized knowledge A dedicated Stack Overflow HUB showcases the latest questions, trending tags, and top contributors.
• Contextual insights Embeddable UI components bring vital Stack Overflow information directly into your Backstage environment.
• Frictionless collaboration Secure, streamlined OAuth authentication with PKCE ensures easy access.
• In-Context questioning Integration allows developers to ask questions and get help within their Backstage workflow (Stack Internal Business and Enterprise only).
• Unified search Integration surfaces valuable Stack Overflow knowledge alongside internal documentation, streamlining information discovery.

Start with a demo Docker image

If you'd like to experiment with this integration without setting up a full Backstage instance, you can quickly test it with this pre-built Docker image:

https://hub.docker.com/r/stackoverflowdocker/stackoverflow-backstage-demo

This image runs a Backstage instance pre-configured with the latest Stack Overflow Internal plugins and demo setup. You just need to pass a few environment variables when starting the container to connect it to your Stack Overflow Internal site.

Required environment variables

Stack Internal Enterprise environment variables

Variable	Description
STACK_OVERFLOW_INSTANCE_URL	The base URL of your Stack Overflow Internal site.
STACK_OVERFLOW_API_ACCESS_TOKEN	A read-only, no-expiry API access token for your Stack Overflow Internal site (used by the search collator to index questions in Backstage search).
STACK_OVERFLOW_CLIENT_ID	The OAuth Client ID from your Stack Overflow application (required to enable secure question creation from within Backstage). This ClientID should have write access.
STACK_OVERFLOW_REDIRECT_URI	The redirect URI where Stack Overflow should send users after OAuth authentication. Typically {app.baseUrl}/stack-overflow-teams. For local use, you can use a redirect service like http://redirectmeto.com/http://localhost:7007/stack-overflow-teams.

Stack Internal Basic and Business environment variables

Variable	Description
STACK_OVERFLOW_TEAM_NAME	The team name or team slug from your Stack Overflow Internal site.
STACK_OVERFLOW_API_ACCESS_TOKEN	A read-only, no-expiry Personal Access Token (PAT) for your Stack Overflow Internal site. Used for indexing content.

Example Docker command

Once you have those values, you can launch the container by running the following commands.

Stack Internal Enterprise example Docker command

docker run -p 7007:7007 \
  -e STACK_OVERFLOW_INSTANCE_URL=https://your-site-url.stackenterprise.co \
  -e STACK_OVERFLOW_API_ACCESS_TOKEN='your-access-token' \
  -e STACK_OVERFLOW_CLIENT_ID=your-client-id \
  -e STACK_OVERFLOW_REDIRECT_URI=http://redirectmeto.com/http://localhost:7007/stack-overflow-teams \
  stackoverflowdocker/stackoverflow-backstage-demo:latest

Stack Internal Basic and Business example Docker command

docker run -p 7007:7007 \
  -e STACK_OVERFLOW_TEAM_NAME=https://your-site-url.stackenterprise.co \
  -e STACK_OVERFLOW_API_ACCESS_TOKEN='your-PAT-token' \
stackoverflowdocker/stackoverflow-backstage-demo:latest

Before you begin: choose your frontend system.

This guide supports both Backstage frontend systems. Your frontend system determines which installation steps you should follow.

• New Frontend System (NFS): If your app uses createApp from @backstage/frontend-defaults and registers functionality through features and extensions, complete the shared backend setup in this guide, then skip the legacy frontend instructions and follow Install on the New Frontend System.

• Legacy frontend system: If your app uses createApp from @backstage/app-defaults with a <FlatRoutes> element tree, follow the guide as written, including the Frontend installation section.

The backend setup is the same for both systems. Only the frontend installation and configuration steps differ.

Integration components

The Backstage Stack Overflow Internal integration uses three plugins:

• Frontend Teams Plugin Provides the user interface elements that display Stack Overflow content and functionality within your Backstage application.
• Backend Teams Plugin Handles API communication between Backstage and your Stack Overflow Internal site.
• Search Collator Plugin (Optional) Indexes all questions from your Stack Overflow Internal site, displaying search results directly within Backstage's search functionality.

This guide details the steps for setting up this integration.

Code example

Our Github repository holds a Backstage Stack Overflow Internal integration already configured with the three plugins. If in doubt, use this example to help configure your own site.

Create a service application (Stack Internal Enterprise only)

To connect your Stack Internal Enterprise site to the Backstage integration, the best approach is for a Stack Overflow administrator to create a service application. Learn more about API applications and Stack Overflow Internal service applications in the Stack Overflow Internal API v3 article.

Other users will see your Backstage service application, so be sure to give it a descriptive name (such as "Backstage"). For the service application domain, specify the domain of your Backstage site.

Once you've created the service application, refresh the page, change its Status to read-write, and click Confirm. Backstage will need the client_id, so be sure to save it to your working document.

If you plan to use the optional search collator plugin, you'll need an access token. Generate an access token by following the instructions in the Secure API Token Generation with OAuth and PKCE article. The secure token doesn't require write access, but we recommend enabling the no_expiry scope. Copy this token and save it to your working document.

The Backstage backend system

Backstage made changes to how the framework's backend system works with their v1.31.0 release. The instructions in this article assume you're using this New Backend System. You can migrate to the new backend system by following the Migrating your Backend to the New Backend System article.

You can use this integration with the older backend system, but these instructions will not apply. Instead, start by completing the Getting Started with Search guide from Backstage. Then follow the instructions in this Stack Overflow search collator GitHub repository.

Backend installation

1. Add the Stack Overflow Internal Backend plugin and collator plugin as dependencies in your Backstage application.

   From your Backstage root directory run:

   yarn --cwd packages/backend add backstage-plugin-stack-overflow-teams-backend
   yarn –cwd packages/backend add backstage-stack-overflow-teams-collator
   

   This will add the plugins to the backend of the application.

2. Import the plugins.

   Edit packages/backend/src/index.ts and add the Teams Backend plugin and collator:

   backend.add(import('backstage-plugin-stack-overflow-teams-backend'));
   backend.add(import('backstage-stack-overflow-teams-collator'));
   

   You can find an example index.ts file in our Github repository.

3. Configure the Backstage application with your Stack Overflow Internal API credentials.

   For security, you shouldn't hard-code sensitive information (such as passwords or access tokens) into your application. Instead, you should store these in the environment and pass them to your application at runtime. How you'll accomplish this depends on your application and environment configuration. What follows is an example using the dotenv library to safely store and pass credentials.

   Install dotenv
   Run the following command to add the dotenv library to your backend:

   yarn --cwd packages/backend add dotenv
   

   Configure dotenv
   Edit the packages/backend/src/index.ts file to load the .env variables into the application. Add the following lines of code:

   import dotenv from 'dotenv'; // Import the dotenv module
   dotenv.config(); // Load environment variables from the .env file into process.env
   

   Create and configure the .env file
   Create a new .env file in the packages/backend folder. Define your environment variables in that file as follows.

   Stack Internal Enterprise .env file

   STACK_OVERFLOW_INSTANCE_URL=your_site_url
   STACK_OVERFLOW_API_ACCESS_TOKEN=your_access_token
   STACK_OVERFLOW_CLIENT_ID=your_clientid
   

   Stack Internal Basic and Business .env file

   STACK_OVERFLOW_TEAM_NAME=team_slug
   STACK_OVERFLOW_API_ACCESS_TOKEN=your_PAT
   

   Ensure git doesn't upload .env
   Add .env to your .gitignore file to prevent git from pushing it to the server:

   # Environment Variables
   .env
   

   Load environment variables
   Your app-config.yaml should contain the following lines.

   Stack Internal Enterprise app-config.yaml file

     stackoverflow:
       baseUrl: ${STACK_OVERFLOW_INSTANCE_URL}
       teamName: ${STACK_OVERFLOW_TEAM_NAME} // optional
       apiAccessToken: ${STACK_OVERFLOW_API_ACCESS_TOKEN}
       client_id: ${STACK_OVERFLOW_CLIENT_ID}
       redirect_uri: ${STACK_OVERFLOW_REDIRECT_URI} // this should navigate to /stack-overflow-teams in your Backstage site
   

   Stack Internal Basic and Business app-config.yaml file

   stackoverflow:
   teamName: ${STACK_OVERFLOW_TEAM_NAME}
   apiAccessToken: ${STACK_OVERFLOW_API_ACCESS_TOKEN}
   

Frontend installation

Set up search

Install the frontend plugin to use the integration functionality and format the indexed questions. As a prerequisite, you'll need to have your SearchPage.tsx file ready for modifications. For more information, read the Backstage Getting Started with Search guide.

In this example, we'll obtain the indexed search results and render them conditionally.

First, install the frontend Stack Overflow plugin. Run:

yarn --cwd packages/app add backstage-plugin-stack-overflow-teams

Edit packages/app/src/components/search/SearchPage.tsx.

By default, SearchPage.tsx displays the search results without conditional formatting. You'll modify this to let the type of returned search results control how the search results appear.

Locate the following section in the existing <SearchResult><SearchResult/> code:

Replace this code with the snippet found in the Backstage Customizing Search documentation as below:

Disregard the error indicators—you'll fix them in the following steps.

1. Import the <List/> component from the Material UI library by adding it to the @material-ui/core import array:

2. Add a default case which uses Backstage's <DefaultResultListItem/> component:

default:
  return (
    <DefaultResultListItem
      key={result.document.location}
      result={result.document}
      highlight={result.highlight}
    />
  );

3. Import the <DefaultResultListItem/> component:

4. Add the StackOverflow case to conditionally render the <StackOverflowSearchResultListItem /> component from the frontend plugin we installed:

case 'stack-overflow':
  return (
    <StackOverflowSearchResultListItem
      key={result.document.location}
      result={result.document}
      highlight={result.highlight}
    />
  );

5. Import the list item component from @backstage-plugin-stack-overflow-teams:

6. Add the Stack Overflow results to the Search accordion.

Locate the <SearchType.Accordion/> component and add the following code snippet to the accordion:

{
  value: 'stack-overflow',
  name: 'Stack Overflow',
  icon: <StackOverflowIcon />,
},

7. Import the <StackOverflowIcon /> component from @backstage-plugin-stack-overflow-teams.

Configuration is complete. Before running the application, ensure all dependencies are installed by running yarn install on the root directory of your Backstage application.

Example SearchPage.tsx code

You can find an example of the SearchPage.tsx used in this article in our Github repository.

Set up the Stack Overflow hub and question modal

The frontend plugin includes the Stack Overflow hub (reusable frontend components) and a modal component you can integrate anywhere in your UI. The hub displays top questions, tags, and users. To incorporate this hub into your Backstage frontend, create a new frontend route and place the route's shortcut within the UI. Additionally, you can add the modal component in a convenient location.

Create a frontend route for the plugin

1. Navigate to your frontend App.tsx file, usually found at packages/frontend/src. Scroll until you see the <Route /> elements. Add a route for the StackOverflowTeamsPage component as follows:

2. Make sure the list item component is imported from the plugin.

3. Create a shortcut for the route (optional). Though not required, we recommend adding this shortcut to the sidebar for convenience.

   To add the shortcut, navigate to packages/app/src/components/Root.tsx. Scroll down to locate the SidebarItem section. Here you'll add a new sidebar item with the Stack Overflow logo. In the UI, clicking the logo will direct users to the route we built earlier.

   

   Stack Internal Business and Enterprise users can also add the "Ask a Question" modal to the sidebar. This makes the button available from anywhere in the Backstage application.

   The <StackOverflowPostQuestionModal /> listens to the event "openAskQuestionModal" regardless of where the event is created. Add a new SidebarItem to create that event, and also add the <StackOverflowPostQuestionModal /> as seen below:

   

   Get all the resources imported from the plugin:

   

Install on the New Frontend System

The instructions above cover Backstage's legacy frontend architecture.

If your app is built with createApp from @backstage/frontend-defaults, and registers functionality through features and extensions, you're on Backstage's New Frontend System (NFS) instead. Follow this section.

If your app uses createApp from @backstage/app-defaults with a <FlatRoutes> element tree, you're on the legacy system — follow the instructions above. Nothing in this section applies to you.

Install the package

Run the following command from your Backstage root directory:

yarn --cwd packages/app add @stackoverflow/backstage-plugin-stack-overflow-teams

Add the feature

packages/app/src/index.tsx, and import the plugin from its /alpha entry point:

import { createApp } from '@backstage/frontend-defaults';
import stackOverflowTeamsPlugin from '@stackoverflow/backstage-plugin-stack-overflow-teams/alpha';

const app = createApp({
  features: [stackOverflowTeamsPlugin],
});

export default app.createRoot();

If your app discovers features automatically through app.packages configuration, you don't need to change any code. The package gets picked up on its own.

That's the whole installation. Unlike the legacy system, the New Frontend System install needs no Root.tsx edits — don't add sidebar items or route elements by hand. Everything below comes from the plugin.

What you get

Installing the feature adds the following extensions, all enabled by default:

• page:stack-overflow-teams — the Stack Internal hub, at /stack-overflow-teams.
• page:stack-overflow-teams/ask-question — the trigger route for the ask-a-question modal.
• nav-item:stack-overflow-teams — the "Stack Internal" sidebar item.
• nav-item:stack-overflow-teams/ask-question — the "Ask a Question" sidebar item.
• api:stack-overflow-teams — the API client that talks to the backend plugin.
• search-result-list-item:stack-overflow-teams — renders indexed questions on the search page.
• search-filter-result-type:stack-overflow-teams — adds "Stack Internal" to the search result type filter.
• app-root-element:stack-overflow-teams/ask-question-modal — mounts the ask-a-question modal at the app root.

Configuration

Configure extensions under app.extensions in app-config.yaml.

app: extensions: # Serve the hub from a different path - page:stack-overflow-teams: config: path: /stack-internal # Opt out of a sidebar item - nav-item:stack-overflow-teams/ask-question: false

The hub path is also the OAuth redirect target. If you change it, update stackoverflow.redirectUri to match, and update the redirect URI registered on your Stack Internal OAuth application, too. A mismatch between these three values is the most common cause of a failed login.

<button onClick={() => window.dispatchEvent(new Event('openAskQuestionModal'))}>
  Ask a question
</button>

// Don't do this — it bypasses route registration
<Route path="/stack-overflow-teams" element={<StackOverflowTeamsPage />} />