Backstage Setup (Developer Portal)

This page describes how the Rocket Club Backstage portal is developed locally and how it is expected to run in production.

Where it lives

• App code: apps/portal/**
• Infrastructure (Terraform): infra/platform/infra/envs/prod (monorepo)

Architecture summary

• Local development: Backstage runs locally; authentication can use direct OIDC.
• Production: Backstage runs on AWS (ECS/Fargate) behind an ALB with OIDC (Kinde).

See also:

• Infrastructure overview: /infra-overview
• CI/CD & deploy workflows: /deployment-ci
• Secrets/SSM reference: /aws-secrets-and-parameters

Prerequisites

• Node (see repo tooling; portal app uses Yarn)
• Docker (for local dependencies if needed)
• AWS CLI configured (for production ops)

Local development

From repo root:

cd apps/portal
yarn install
yarn start

Backstage frontend/backend will run locally.

Repository layout

Backstage is a monorepo-style app inside apps/portal/:

• apps/portal/packages/ - app packages (frontend + backend + shared libs)
• apps/portal/plugins/ - custom plugins and their modules

Creating a new plugin

From apps/portal/:

yarn new

Follow the prompts to scaffold a plugin.

Backend package

The backend lives at apps/portal/packages/backend/.

In most cases you’ll run everything via yarn start from apps/portal/, but you can also run just the backend from its folder.

Authentication (Kinde)

Kinde settings typically include:

• Application homepage URI: https://rocketclub.online
• Application login URI: https://portal.rocketclub.online
• Callback URLs:
  • Local: http://localhost:7007/api/auth/oidc/handler/frame
  • Production: https://portal.rocketclub.online/api/auth/oidc/handler/frame

Kinde-specific notes:

• tokenEndpointAuthMethod: client_secret_post (Kinde doesn’t support client_secret_basic).
• Kinde uses offline scope (not offline_access).
• An audience parameter may be required for the userinfo endpoint.

Production notes

Production infrastructure is provisioned via this monorepo’s Terraform (see infra/platform/infra/envs/prod).

At a minimum, production needs:

• ECS service/task for Backstage
• Postgres database (Aurora)
• Secrets Manager entries for Backstage configuration (see /aws-secrets-and-parameters)