🐛 Bug Report: "Getting Started" instructions need updates

[jerryjvl]

📜 Description

The first failure was when I used the Node version in the linked nvm docs (Node 22), which resulted in issues when yarn tried to install isolated-vm -- once I reverted with nvm install 20, the steps started working.

The second failure happens when I try to use guest auth method to confirm the base create-app worked; I get errors processing the guest user in the org.yaml, after adding general allow rules in every config file and did various attempts to rebuild the app, the runtime warnings about disallowed entity types went away, but I have no idea precisely what fixed those... regardless though, when I try to use Guest login in the install I first get a popup that "Failed to sign in as a guest using the auth backend. Do you want to fallback to the legacy guest token?", and if I accept that I get nothing but Authentication errors in the app that I cannot escape from.

The third mayb-failure is that create-app appears to create a backend with a bunch of /alpha imports in it, that do not seem to match with the config in the Backend repo itself, so I suspect the bootstrap template is also out of date.

The combination of auth errors and uncertainty whether anything should stay /alpha to work, have left me in a place where I'm just going to have to hope that if I add a proper GitHub login that my problems will go away, but because it's not clear there isn't a more fundamental problem in this bootstrap, I may get myself lost in a sea of red herrings as I progress further.

👍 Expected behavior

Diligently following the "Getting Started" steps should produce a setup that actually works once you run yarn dev!

👎 Actual Behavior with Screenshots

I didn't keep track of all the specific messages on the console, but the most notable popup text is included in the description above.

👟 Reproduction steps

Follow the exact steps in "Getting started" as-written on a clean MacOS system (I do not think other OS would have a better outcome based on what I understand about the context of the errors I have described).

📃 Provide the context for the Bug.

This is not my first Backlog install, but the last one I did predates the new backend/frontend work, so I wanted to follow the steps for a from-scratch setup for my new employer. However, my confidence in the correctness of the bootstrap setup is extremely low based on the obvious discrepancies and errors I experience.

I'm sure I'll manage to work myself towards a functioning system by replacing anything that does not seem to work, but I have no idea how a new developer interested in giving this a try is meant to walk away with a positive experience.

🖥️ Your Environment

Clean install from-scratch on MacOS following the exact steps in Getting started.

👀 Have you spent some time to check if this bug has been raised before?

• I checked and didn't find similar issue

🏢 Have you read the Code of Conduct?

• I have read the Code of Conduct

Are you willing to submit PR?

None

[awanlin]

Hi @jerryjvl, just wanted to follow up on a few items here.

Backstage will support Node 22 with in the 1.33.0 release that goes out on November 19th, there's a bit of time where we can't alway perfectly line up things so there's no gaps during the Node LTS change. I do have an open PR to update the link on the getting started guide to point to the Backstage Node Version Policy as it makes this transition period a bit more clear: #27415

Regarding the /alpha imports, those have been in place for a few months now but only recently changes from being no longer Alpha in the last release. The create-app template was not updated but that has been corrected and going forward will not have them - #27534. There's no fundamental difference between the two just where the export is but I can understand it's not clear in its current form.

As for your guest auth issue that is one I don't have any details to share. I recently setup an old MacBook that I had reset to factory settings to dry run a Backstage setup from scratch. I did not have any issues with auth. You should not need to make any changes for this to work after running npx @backstage/create-app@latest. Can you share more details about this: "after adding general allow rules in every config file"?

[notwatermango]

Having the same issue with guest auth, using Backstage v1.34.0, node v20.18.1

Failed to sign in as a guest using the auth backend. Do you want to fallback to the legacy guest token?

Yes

Takes me to the /catalog page but won't load anything

One of the logs
[backend]: 2025-01-09T08:12:20.693Z rootHttpRouter info [2025-01-09T08:12:20.693Z] "GET /api/catalog/entity-facets?facet=metadata.namespace HTTP/1.1" 401 577 "http://localhost:3000/" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36" type=incomingRequest date=2025-01-09T08:12:20.693Z method=GET url=/api/catalog/entity-facets?facet=metadata.namespace status=401 httpVersion=1.1 userAgent=Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36 contentLength=577 referrer=http://localhost:3000/

I am not facing this issue using google auth

What I want to achieve is simply developing using yarn dev without having to sign in to google on every hot reload...

[Rugvip]

@notwatermango you'll want to make sure the guest auth provider is installed in the backend so that it can be used by the frontend during local development. It's installed out of the box in a new app, but this is the important bit:

backstage/packages/backend/src/index.ts

Line 35 in 29596ac

backend.add(import('@backstage/plugin-auth-backend-module-guest-provider'));

. It might also be that there's an issue communicating with the provider, please open a new issue with more details if that's the case.

I'm gonna close this issue as it doesn't have any concrete next steps, but please do open new issues for any specific individual problems you run into when following the getting started guide.

[notwatermango]

I already done all instructions, to the point of starting up a new backstage project just to check this issue.

[notwatermango]

For me the fix is using Firefox instead of Chrome