Skip to main content
Version: Next

Building a custom portal

There are three ways to run a Backstage portal for OpenChoreo:

PathChoose it when
The stock portalThe portal the control-plane Helm chart deploys is enough, and you only need configuration.
A custom portal (this page)You want the full OpenChoreo portal, plus your own plugins, pages or branding, as a repository you own and build.
Plugins in your own BackstageYou already run a Backstage app and want to add OpenChoreo to it.

A custom portal starts as a copy of the stock portal, generated by @openchoreo/create-portal. It is a thin Backstage app: the portal itself comes from the published @openchoreo/backstage-portal-app and @openchoreo/backstage-portal-backend packages, so the repository holds only configuration and whatever you add. You do not fork openchoreo/backstage-plugins.

Available from 1.4.0

@openchoreo/create-portal and @openchoreo/backstage-portal-app are first published with 1.4.0. Earlier releases have no custom-portal path; fork the upstream repository instead.

Prerequisites​

  • Node.js 20 or 22, and Yarn through corepack enable. The generated repository pins its own Yarn release.
  • git, so the CLI can put the new portal in a repository with an initial commit. Upgrades are git merges.
  • An OpenChoreo control plane on the same release, for the portal to connect to.
  • Docker and access to a container registry, to build and ship the image.

Create the portal​

npx @openchoreo/create-portal

npm init @openchoreo/portal runs the same CLI. It asks for a name, then:

  1. Writes the template into ./<name>, with every @openchoreo/* package pinned to the CLI's own release through resolutions in the root package.json.
  2. Creates app-config.local.yaml from the bundled example.
  3. Commits the untouched template.
  4. Runs yarn install and yarn tsc.

The template ships inside the CLI package, so creating a portal needs only the npm registry.

FlagMeaning
--name <name>Portal name (lowercase letters, digits, dashes). Skips the prompt.
--path <dir>Write into this directory instead of ./<name>. It must be empty or not exist yet.
--registry <url>Registry to install @openchoreo/* from. Defaults to the registry npm uses for @openchoreo, otherwise npmjs.
--skip-installSkip yarn install and yarn tsc.
--template-path <dir>Use a template directory instead of the bundled one.

To pin a specific release, run that version of the CLI: npx @openchoreo/create-portal@1.4.0.

Using a registry mirror​

Without --registry, the CLI uses the registry npm resolves @openchoreo/* from: @openchoreo:registry in your .npmrc, otherwise npm's registry. A mirror configured once in .npmrc therefore carries over for @openchoreo/* without a flag, and so does npm init @openchoreo/portal --registry <url>.

The registry is written to the portal's .yarnrc.yml for the openchoreo scope only. Yarn does not read .npmrc, so every other package still comes from Yarn's default registry. To install those through your mirror as well, set npmRegistryServer in the portal's .yarnrc.yml.

If the registry needs authentication, add an npmAuthToken for the openchoreo scope to your user-level ~/.yarnrc.yml rather than committing it. A plain http:// registry is added to unsafeHttpWhitelist automatically, because Yarn otherwise refuses it.

What you get​

my-portal/
├── packages/app/ # the frontend: feature discovery installs the portal
├── packages/backend/ # the backend: portalBackendFeatures plus your plugins
│ └── Dockerfile # the same image build as the stock portal
├── plugins/ # your own plugins (`yarn new`)
├── app-config*.yaml # the stock portal's configuration, now yours
├── templates/, examples/ # the OpenChoreo scaffolder templates
└── .openchoreo-portal.json # the release this repository started from

The frontend is createApp() with no feature list. app.packages: all in both app-configs turns on Backstage feature discovery, which installs the portal from the @openchoreo/backstage-portal-app dependency. A discovery.test.ts fails if that ever stops happening, which would otherwise show up only as an empty page.

The backend adds portalBackendFeatures, the stock portal's complete backend.

The Portal Assistant is not included. It ships only in the stock portal image.

Run it locally​

cd my-portal
yarn start # frontend on :3000, backend on :7007

Local settings live in app-config.local.yaml, which git ignores. The defaults target a local k3d install on *.openchoreo.localhost:8080. For any other control plane, point openchoreo.baseUrl, thunder.baseUrl and the auth.providers.openchoreo-auth URLs at it.

The sign-in client must accept the local redirect URL http://localhost:7007/api/auth/openchoreo-auth/handler/frame. See Authentication.

Add plugins​

Optional OpenChoreo plugins, community plugins and your own plugins all install the same way: as dependencies of the portal.

  • Frontend. yarn workspace app add <package> is the whole installation. Discovery picks up any dependency that default-exports a frontend feature from its root or ./alpha entry point. A plugin with only named exports goes into createApp({ features: [...] }) in packages/app/src/App.tsx.
  • Backend. yarn workspace backend add <package>, then add backend.add(import('<package>')) to packages/backend/src/index.ts.
  • Your own. yarn new scaffolds a plugin into plugins/.

Customize​

Everything the portal contributes is a Backstage New Frontend System extension, so most changes are configuration:

app-config.yaml
app:
extensions:
# Hide a tab or page you don't use
- entity-content:openchoreo-observability/wirelogs: false
# Move a tab into another group
- entity-content:openchoreo-ci/workflows:
config:
group: development

See Feature discovery for switching extensions off.

To replace a piece outright, override its extension with a frontend module for the plugin that owns it. A module swaps only the extensions it lists and keeps the rest of the plugin. Do not create a second plugin with the same plugin ID instead: Backstage keeps only one of the two, so the original plugin's other extensions and APIs disappear. An extension ID has the form <kind>:<plugin ID>/<name>: give your extension the same kind and name, and the module the same plugin ID.

For example, to replace the CI plugin's build tab (entity-content:openchoreo-ci/workflows), pass a module to createApp in packages/app/src/App.tsx. The app already depends on the two Backstage packages it imports, at the versions the portal uses:

packages/app/src/App.tsx
import { createApp } from "@backstage/frontend-defaults";
import { createFrontendModule } from "@backstage/frontend-plugin-api";
import { EntityContentBlueprint } from "@backstage/plugin-catalog-react/alpha";
import { PageLoader } from "@openchoreo/backstage-design-system";

const buildTab = EntityContentBlueprint.make({
name: "workflows",
params: {
path: "/workflows",
title: "Build",
loader: () => import("./BuildTab").then((m) => <m.BuildTab />),
},
});

export default createApp({
features: [
createFrontendModule({ pluginId: "openchoreo-ci", extensions: [buildTab] }),
],
advanced: {
loadingElement: <PageLoader />,
},
}).createRoot();

The new extension replaces the original completely, so set any of its parameters you still want, such as filter or group.

Logo, product name and brand color are runtime configuration under app.branding; see Theming and branding. Favicons and the web manifest live in packages/app/public/.

Optional capabilities are switched with openchoreo.features.*.enabled. Keep them matching what your control plane actually runs; the Helm chart sets them for you in production.

Build and deploy​

The template ships a yarn.lock seeded with the dependency set the release was tested with. The first yarn install trims it to what your portal uses; commit the result. Then build the image:

docker build . -f packages/backend/Dockerfile \
-t registry.example.com/acme/portal:0.1.0
docker push registry.example.com/acme/portal:0.1.0

The image build runs yarn install itself, so it cannot see a registry token kept in your ~/.yarnrc.yml. If your mirror needs one, pass that file in as a BuildKit secret. Add --mount=type=secret,id=yarnrc,target=/home/node/.yarnrc.yml,uid=1000 to both RUN steps in packages/backend/Dockerfile that run Yarn (yarn install --immutable and yarn workspaces focus), then build with:

docker build . -f packages/backend/Dockerfile \
--secret id=yarnrc,src=$HOME/.yarnrc.yml \
-t registry.example.com/acme/portal:0.1.0

The token is available only while those steps run and does not end up in the image.

The image replaces the stock openchoreo-ui image, and reads the same configuration from the chart. Point the control-plane chart at it:

helm upgrade openchoreo-control-plane oci://cr.openchoreo.dev/openchoreo/helm-charts/openchoreo-control-plane \
--version 0.0.0-latest-dev \
--namespace openchoreo-control-plane \
--reuse-values \
--set backstage.image.repository=registry.example.com/acme/portal \
--set backstage.image.tag=0.1.0

Use a new tag for every build. With an unchanged tag, nodes that already have the image keep running the old one.

Upgrade to a new release​

Each release's template is published as a tag of openchoreo/portal-template. Merging that tag brings in everything the release changed: the @openchoreo/* versions, configuration, the Dockerfile, the scaffolder templates and .openchoreo-portal.json. Git keeps your own changes.

Once, right after creating the portal, record the release you started from, which .openchoreo-portal.json names, as the merge base. Later upgrades build on this merge, which changes no files:

git remote add portal-template https://github.com/openchoreo/portal-template
git fetch portal-template --tags
BASE=$(node -p "require('./.openchoreo-portal.json').release")
git merge -s ours --allow-unrelated-histories "$BASE" \
-m "chore: record portal-template $BASE as the upgrade base"

Then, for each upgrade, merge the tag of the release you are moving to:

git fetch portal-template --tags
git merge v1.5.0

Conflicts appear only where you changed the same lines as the release. For yarn.lock, take the release's copy (git checkout --theirs yarn.lock) and let yarn install add your dependencies back. Then run yarn install && yarn tsc && yarn test:all and rebuild the image.

Upgrade the portal together with the control plane, since a portal expects the API of its own release.