Migrate from Roadie to self-hosted Backstage

Ownership data usually disappears because some entities were created only through the Roadie UI or API and never existed as a catalog-info.yaml file in a repository. Backstage reads the catalog from descriptor files, so anything that lives only in Roadie's database has no source to load from. Before cutover, compare the entity list from your Roadie export against the entities discovered from your repositories, and list every gap. For each gap, write a catalog-info.yaml with the owner (a Group or User reference), the lifecycle and the system it belongs to, then commit it to the owning repository. The descriptor format is described in the Backstage descriptor format documentation. Treat any entity without a committed file as unfinished until its owner has reviewed it.

Guest access is not safe for production because it lets anyone who reaches the portal sign in without a verified identity. Leaving it on is a common carry-over from a development or pilot setup, where it made testing easier. Before go-live, remove the guest provider from the auth configuration, confirm that unauthenticated requests to the catalog and API endpoints are rejected, and test sign-in with a real provider account. The Backstage authentication documentation advises against offering guest access in production. Add a check to your deployment pipeline or review checklist so the setting cannot return unnoticed in a later configuration change.

When sign-in resolvers map the same person to different identities, users see duplicate or wrong catalog ownership, and permissions and group membership stop matching the people they describe. This happens when a user signs in with GitHub in one case and Google or Okta in another, and each provider produces a separate user entity. The fix is to configure sign-in resolvers so every provider resolves to the same identity, typically by matching on a shared email address or a verified username that maps to an existing User entity. The Backstage authentication documentation recommends this approach. Test each provider with the same test account before cutover and confirm that all of them land on one User entity in the catalog.

The catalog goes stale when discovery and ingestion stop running or point at the wrong sources after the Roadie integrations are switched off. Backstage only knows about entities that its locations and providers have ingested, so a missing integration or a broken token leaves old or empty data in place. Before cutover, confirm that every repository provider and Location is configured, that the service account token has read access, and that a scheduled refresh completes without errors. After cutover, check the catalog for entities whose last update is older than expected and for entities that were deleted in source repositories but still appear in the portal. Assign one person to review ingestion errors for the first weeks.

Falling behind on upgrades leaves the portal exposed to known vulnerabilities and makes each later upgrade harder. Backstage's main release line ships monthly, and its versioning policy says high and critical severity vulnerabilities will always be backported to releases from the last 6 months if feasible. A portal that stays on a release outside that window may not receive those fixes, so the security exposure grows with each month of delay. Also check the Node.js requirement: the versioning policy says Backstage supports exactly two adjacent even-numbered Node.js releases, so runtime upgrades can be required as well. Set a recurring upgrade owner, schedule a monthly review of the release notes, and keep a staging instance on the next release line to catch breaking changes early.

You know the export is complete only when you have compared it against the live Roadie catalog and resolved every difference, not when the export file exists. Count entities by kind in Roadie and in the exported YAML, then check relationships such as owners, systems and dependencies on a sample of each kind. Include TechDocs source locations, scorecard or custom metadata you still need, and any API definitions attached to API entities. Verify that the exported files parse and load into a test Backstage instance before you change any DNS, bookmarks or team processes. Keep the Roadie account active until the test instance matches the signed-off inventory, because the contract end is not the right trigger for checking the data.

Your team can run the cutover if it has engineers who can operate Kubernetes or another host, PostgreSQL, Backstage configuration and an identity provider, and if someone owns upgrades afterward. Outside help is most useful for the parts that are easy to get wrong: writing the entity gap list, hardening authentication, and proving that the new instance matches the verified export. DeployOpen plans, implements, hardens, backs up, upgrades and documents self-hosted platforms inside the client's own infrastructure, and most engagements are fixed-scope with the scope and timeline agreed in writing before work starts. Ask any provider to name the specific cutover checks it will run and the evidence it will hand over.

The migration cost depends on the work you assign, not on a fixed package. The main cost drivers are the size of your catalog, how many integrations and custom plugins you need to rebuild, how many authentication providers and sign-in resolvers you configure, and how much of your TechDocs estate moves over. Some costs are one-time, such as discovery, build-out, cutover and training. Others recur, such as hosting, PostgreSQL, monthly upgrades and the platform engineers who run the portal. Backstage itself has no license fee, since the project is Apache-2.0 licensed and has no paid edition. Ask any implementation partner for a quote built from a written scope that lists each component separately, and confirm which Roadie charges end when the contract ends.

The timeline is driven by scope rather than by the Backstage codebase. Duration grows with the number of entities to verify, the integrations to re-create, the custom plugins to port, the identity provider to configure and the number of teams that must test the new portal before cutover. A smaller catalog with standard integrations moves faster than one with many custom plugins and scorecards. Plan a parallel run so the old and new portals show the same ownership data before you retire Roadie. Ask for a timeline in the written scope, with milestones for discovery, build, parallel run and cutover, and confirm the Roadie contract end date so the cutover window fits inside it.

A team that already runs Kubernetes, PostgreSQL and a CI/CD pipeline can do much of this work, because the catalog format is the same Backstage model. The harder parts are authentication, custom plugin maintenance, search and TechDocs hosting, and the monthly upgrade cadence that Backstage follows. Backstage's main release line ships monthly, and its next line ships weekly, so someone must own upgrades after launch. Assess your team against those skills before you decide. If you want outside help, DeployOpen plans, implements, integrates, hardens, backs up and upgrades self-hosted platforms in your own infrastructure under a fixed-scope written agreement, and offers retainers for ongoing support.

In most cases the catalog-info.yaml descriptor files that live in your repositories stay as they are, because Backstage catalog entities use the same YAML format regardless of who hosts the portal. You should still check each file against the Backstage descriptor format for the kinds you use, such as Component, API, Resource, System, Domain, Group, User, Template and Location. Entities created only through the Roadie UI or API will not be in your repositories, so they need to be exported and committed before cutover. Also check for Roadie-specific annotations or plugin settings that Backstage does not read, and confirm each one with your engineers before you retire the old portal.

Yes, authentication must be configured again in your own Backstage, although your identity provider does not change. Backstage ships 19 built-in authentication providers, including GitHub, GitLab, Google, Azure, Okta, Auth0, OneLogin, Bitbucket, Cloudflare Access, AWS ALB, Google IAP and generic OIDC. Configure sign-in resolvers so every provider resolves to the same identity, which keeps ownership consistent across sign-in methods. Do not offer guest access in production. Authentication is a security boundary, so include it in your threat model and in any security testing before go-live.

TechDocs content is written as Markdown next to the code, so the source files usually stay in your repositories. What you must rebuild is the TechDocs pipeline in your own environment, because documentation sites are built with MkDocs and its plugins in your infrastructure. Check the MkDocs plugins your sites use and confirm they run in your build. Also decide where the built sites are stored and who can read them, since access rules move to your own setup. Test a sample of sites in the new portal and compare them with the old ones before you cut over.

No. Backstage is an open source framework released under the Apache License 2.0, and the project itself offers no paid edition. Your costs come from the infrastructure you run it on, the people who operate it and any commercial services you choose to buy around it. Confirm the license terms for every plugin you install, because third-party plugins may be licensed separately. Note that this differs from self-managed editions of other portals, which still require a vendor license key. Check the license file in the Backstage GitHub repository and your plugin sources before finalizing the design.

Plan for regular upgrades from the start. Backstage's main release line ships monthly, and its versioning policy says high and critical vulnerabilities are backported to releases from the last six months where feasible. Supported Node.js versions also change with releases, so check the versioning policy for the current pair before each upgrade. Build upgrades into your operating model with a named owner, a test environment and a rollback plan. Ask any partner to show how they handle upgrades, backups and documentation for your environment.