Practice: Turning one-off customer builds into reusable platform features and internal tooling
Generated by Claude through GigAI 0.1.11.10 on 2026-10-12.
Main tool: Backstage · Backstage puts the catalog, software templates, TechDocs and a plugin model in one open source portal that runs on a laptop, so every part of turning a one-off customer build into a reusable paved path can be practised in one place. · Alternatives: Port and Cortex are hosted developer portals that trade plugin-level control for less operational work; Cookiecutter scaffolds repos without a catalog or portal; LaunchDarkly, Unleash and OpenFeature provide runtime feature flags that Backstage does not; Terraform modules and Helm charts package reusable infrastructure rather than a paved path for developers.
Every step links into the tool's own documentation; links were checked on 2026-10-12 · version 1
Setup (one time)
1. Install the prerequisites listed in the getting started guide: a supported Node.js release, yarn, git and Docker.
Backstage is a Node.js monorepo and the later steps need containers for PostgreSQL and Redis. Getting versions right first avoids confusing install failures.
Explained in: Getting Started | Backstage Software Catalog and Developer Platform (backstage.io), checked 2026-10-12
Done when: Version checks for Node.js, yarn, git and Docker all print versions the guide accepts.
2. Check that your Node.js version is one the Backstage release policy currently supports, and switch if it is not.
Backstage supports only specific Node.js release lines, and an unsupported one breaks the build in ways that look like your own mistakes.
Explained in: Release & Versioning Policy | Backstage Software Catalog and Developer Platform (backstage.io), checked 2026-10-12
Done when: Your active Node.js version matches a release line named in the policy.
3. Create a new Backstage app with the create-app command and start it in development mode.
This gives you a working portal with the catalog, templates and TechDocs already wired in, which every later step customizes.
Explained in: Backstage (backstage.io), checked 2026-10-12
Done when: The Backstage home page loads in your browser from localhost and the terminal shows the frontend and backend running.
4. Complete the software templates prerequisites, including a source control integration token for a personal test account.
Templates publish new repositories, so the golden path step fails without an integration configured.
Explained in: Backstage Software Templates | Backstage Software Catalog and Developer Platform (backstage.io), checked 2026-10-12
Done when: The Create page lists at least one example template and the backend log shows no integration errors.
Steps
1. Run the app and explore the software catalog: open the example components, their owners, and their relations.
The catalog is the centre of the portal, and you need to see what a registered piece of software looks like before modelling your own customer work.
Explained in: Backstage Software Catalog | Backstage Software Catalog and Developer Platform (backstage.io), checked 2026-10-12
Done when: You can open an example component page and name its owner, type and lifecycle from the screen.
2. Write a catalog descriptor file for one past customer build and register it in the catalog by its repository location.
A one-off build that is not in the catalog is invisible to the next engagement. Registering it is the first step toward reuse.
Explained in: Backstage Software Catalog | Backstage Software Catalog and Developer Platform (backstage.io), checked 2026-10-12
Done when: Your customer build appears in the catalog list with the name and description you wrote.
3. Create Group entities for a field team and a platform team, then model the build as a Component in a System with an API, with each part owned by the right group.
Platform as a product only works when ownership and the interface between field and platform teams are explicit. The system model is how Backstage records who provides what to whom.
Explained in: Technical overview | Backstage Software Catalog and Developer Platform (backstage.io), checked 2026-10-12
Done when: The component page shows the platform team as owner of the shared API and the field team as owner of the customer component, with the relation graph linking them.
4. Write a generalization decision for three pieces of the customer build, placing each in the app, a plugin package or a common package using the code placement guidance.
Deciding what to generalize is a judgement about how many consumers a piece has. The package architecture gives concrete homes for customer-specific, shared and cross-cutting code.
Explained in: Architecture overview | Backstage Software Catalog and Developer Platform (backstage.io), checked 2026-10-12
Done when: You have a three-row note naming each piece, its chosen package location and the reason, and at least one piece is deliberately left customer-specific.
5. Compare the Backstage release your app installed against the latest release notes and list the breaking changes that touch your catalog, templates and TechDocs.
Shared tooling only stays reusable if it survives upgrades, so you need the habit of checking what changed between the version you have and the current one.
Explained in: v1.55.0 | Backstage Software Catalog and Developer Platform (backstage.io), checked 2026-10-12
Done when: You have a written list of the breaking changes that apply to your app and the upgrade action for each.
6. Run a software template from the Create page to scaffold a new service from the pattern in your customer build, and follow the task log to completion.
A template is the golden path itself: it turns the repeated first week of an engagement into a form anyone on the field team can fill in.
Explained in: Backstage Software Templates | Backstage Software Catalog and Developer Platform (backstage.io), checked 2026-10-12
Done when: The task finishes with all steps green, a new repository exists in your test account, and the new component is registered in the catalog.
7. Write a short documentation site next to the scaffolded component's code and view it rendered in the component's docs tab through TechDocs.
A paved path nobody can find instructions for does not get used. Docs kept beside the code stay current with the template.
Explained in: TechDocs Documentation | Backstage Software Catalog and Developer Platform (backstage.io), checked 2026-10-12
Done when: The Docs tab of your component renders your pages, and they also appear in the portal's documentation list.
8. Configure a per-customer configuration file layered over the base config that changes branding, catalog locations and enabled integrations, then start the app with it.
This is the toggle pattern at the portal level: one codebase and a small overlay per customer, instead of a fork per customer. Backstage has no runtime flag service, so config layering is the closest built-in equivalent.
Explained in: Configuration | Backstage Software Catalog and Developer Platform (backstage.io), checked 2026-10-12
Done when: Starting the app with customer A's overlay and then customer B's shows different titles and catalog contents from the same code.
9. Configure scaffolder template filtering so that each customer overlay shows only the templates meant for that customer or team.
Per-customer variation applies to golden paths too. Filtering lets one template library serve many engagements without exposing the wrong path.
Explained in: v1.55.0 | Backstage Software Catalog and Developer Platform (backstage.io), checked 2026-10-12
Done when: The Create page shows a different set of templates under each customer configuration.
10. Package one field customization as its own plugin package in the monorepo, with a pinned version, and install it into the app from that package.
A customization that lives in a named, versioned package can be reproduced in the next deployment and built by any pipeline. Code pasted into the app cannot.
Explained in: Architecture overview | Backstage Software Catalog and Developer Platform (backstage.io), checked 2026-10-12
Done when: A clean checkout followed by a locked install and a build produces the app with your plugin loaded, with no manual edits.
11. Configure the backend to use PostgreSQL and a Redis cache running in local containers in place of the in-memory defaults.
The in-memory database loses the catalog on every restart. A real database and cache are the minimum for a portal that several engagements share.
Explained in: Architecture overview | Backstage Software Catalog and Developer Platform (backstage.io), checked 2026-10-12
Done when: After a backend restart your registered components are still present, and the backend log shows connections to PostgreSQL and Redis.
12. Configure sign-in and restrict who can register catalog entities and run templates, working through the operator responsibilities in the threat model.
Templates execute actions with the portal's credentials and catalog input is partly untrusted. A portal shared between field and platform teams must be locked down before it carries customer work.
Explained in: Backstage Threat Model | Backstage Software Catalog and Developer Platform (backstage.io), checked 2026-10-12
Done when: Guest access is off, a signed-in test user can run only the allowed templates, and you have a checklist marking each operator responsibility as met or open.
Back to Turning one-off customer builds into reusable platform features and internal tooling