backstage: Techdocs CLI `serve` results in a 404 error

Expected Behavior

Running npx @techdocs/cli serve displays the techdocs

Actual Behavior

Running npx @techdocs/cli serve displays a 404 page

Steps to Reproduce

Set up a local mkdocs repo
npx @techdocs/cli serve
The 404 will appear in the opened browser window

Context

This seems to be a regression in 1.0.0. npx @techdocs/cli@1.0.0 serve displays the buggy behaviour. npx @techdocs/cli@0.8.17 serve works as expected. The logs for the docker container that is spawned contain a 404 error, snippet below:

INFO     -  Documentation built in 1.95 seconds
INFO     -  [05:30:43] Serving on http://0.0.0.0:8000/
WARNING  -  [05:30:47] "GET /techdocs/index.html HTTP/1.1" code 404

About this issue

Original URL
State: closed
Created 2 years ago
Reactions: 9
Comments: 16 (14 by maintainers)

Most upvoted comments

Hey folks, this was resolved by #11467. I can confirm that it’s fixed on master. Happy to close this.

Niksko on May 17, 2022

I’ve submitted a fix above. I’m really puzzled as to why this isn’t reproducible for people, the fix is fairly straightforward.

For those who can’t reproduce: when you load the http://localhost:3000/docs/default/component/local/ after running serve, what URL does your browser request when it requests the techdocs index.html?

For me:

Version 1.0.0: The browser requests http://localhost:3000/api/techdocs/index.html which returns a 404
Version 0.8.17: The browser requests http://localhost:3000/api/index.html which returns a 200

The bug is that when the embedded-app is resolving the base url for the techdocs API, it used to read the value from config, and it was hardcoded to http://localhost:3000/api. The change I reference in the PR removes this, and so the base url for the techdocs API now resolves to http://localhost:3000/api/techdocs, as it should for a real Backstage installation.

The techdocs-cli when running with the embedded-app (i.e. @techdocs/cli serve) proxies requests to http://localhost:3000/api to the mkdocs container. When it does the proxying, it strips the api portion of the path, but it wasn’t stripping the techdocs portion of the path that was added above.

Niksko on Apr 23, 2022

+1 on fixing this (haven’t gotten to try @Niksko’s fix but hope it works).

folks at my org have found techdocs-cli super unstable. pretty much every update brings some issue that breaks local workflows. would love to see more focus on stability in future techdocs cli releases. (don’t mean to be nagging. i realize it’s a hard thing to get right and that i’m not proposing any solutions 😃 )

zhammer on May 10, 2022