🐛 Bug Report: Bad TechDocs Links For Kroki Generated Images

[saheljalal]

📜 Description

I'm not sure what's going on with my Backstage deployment but for TechDocs pages that are using the Kroki service to generate images, the images are not rendering. Seeing this:

Backstage logging shows something like this with 404 response:

[1] 2023-04-14T22:00:16.052Z backstage info ::1 - - [14/Apr/2023:22:00:16 +0000] "GET /api/techdocs/static/docs/default/component/my-component/my-page/Noneimages/kroki_generated/authentication-0545d30de576afd682323e22b7501246.svg HTTP/1.1" 404 - "http://localhost:3000/" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/112.0.0.0 Safari/537.36" type=incomingRequest

The local images appear to be created successfully and are located at the root folder under my-component/images/kroki_generated so it looks like the paths generated are incorrect. I can request the svg from the API with the correct path manually using curl. The end to end integration fails with local strategy and GCS in my deployment as well.

Additionally, running the same project locally with mkdocs serve works perfectly fine so something feels broken between the Backstage TechDocs backend and plugin possibly.

The part the doesn't make sense is the Noneimages/ bit which looks like some Python parsing issue maybe?

👍 Expected behavior

Render all images correctly on the site.

👎 Actual Behavior with Screenshots

Returns 404 for missing image link, and appears to generate incorrect path.

👟 Reproduction steps

This is occurring in my project which I've upgraded several times, I haven't tried with a new scaffolded project recently. But the main pieces would be:

1. Create a Backstage project
2. Add TechDocs packages and configure
3. Install mkdocs
4. Install plugins mkdocs-techdocs-core and mkdocs-kroki-plugin
5. Set up TechDocs project with mkdocs.yml including

   plugins:
   - techdocs-core
   - kroki:
     ServerURL: !ENV 'KROKI_SERVICE_URL'
     DownloadImages: true

6. Try to render docs with embedded diagrams like this:

   ```kroki-mermaid
   classDiagram
   direction TB
   ...

7. Render the page with Backstage

📃 Provide the context for the Bug.

This is a blocker for us to be able to use diagramming with Kroki.

🖥️ Your Environment

yarn run v1.22.19
$ /Users/.../node_modules/.bin/backstage-cli info
OS:   Darwin 22.3.0 - darwin/arm64
node: v16.18.0
yarn: 1.22.19
cli:  0.22.5 (installed)
backstage:  1.12.1

Dependencies:
  @backstage/app-defaults                          1.2.1
  @backstage/backend-app-api                       0.4.1
  @backstage/backend-common                        0.18.3
  @backstage/backend-dev-utils                     0.1.1
  @backstage/backend-plugin-api                    0.5.0
  @backstage/backend-tasks                         0.5.0
  @backstage/catalog-client                        1.3.0, 1.4.0
  @backstage/catalog-model                         1.1.5, 1.2.1
  @backstage/cli-common                            0.1.12
  @backstage/cli                                   0.22.5
  @backstage/config-loader                         1.1.9
  @backstage/config                                1.0.6, 1.0.7
  @backstage/core-app-api                          1.6.0
  @backstage/core-components                       0.12.3, 0.12.5
  @backstage/core-plugin-api                       1.3.0, 1.5.0
  @backstage/errors                                1.1.4, 1.1.5
  @backstage/eslint-plugin                         0.1.2
  @backstage/integration-aws-node                  0.1.2
  @backstage/integration-react                     1.1.11
  @backstage/integration                           1.4.2, 1.4.3
  @backstage/plugin-api-docs                       0.9.1
  @backstage/plugin-app-backend                    0.3.43
  @backstage/plugin-auth-backend                   0.18.1
  @backstage/plugin-auth-node                      0.2.12
  @backstage/plugin-catalog-backend-module-github  0.2.6
  @backstage/plugin-catalog-backend                1.8.0
  @backstage/plugin-catalog-common                 1.0.10, 1.0.12
  @backstage/plugin-catalog-graph                  0.2.28
  @backstage/plugin-catalog-import                 0.9.6
  @backstage/plugin-catalog-node                   1.3.4
  @backstage/plugin-catalog-react                  1.2.4, 1.4.0
  @backstage/plugin-catalog                        1.9.0
  @backstage/plugin-events-node                    0.2.4
  @backstage/plugin-github-actions                 0.5.16
  @backstage/plugin-home                           0.4.30
  @backstage/plugin-kubernetes-backend             0.9.4
  @backstage/plugin-kubernetes-common              0.6.1
  @backstage/plugin-kubernetes                     0.7.9
  @backstage/plugin-org                            0.6.6
  @backstage/plugin-permission-common              0.7.3, 0.7.4
  @backstage/plugin-permission-node                0.7.6
  @backstage/plugin-permission-react               0.4.11, 0.4.9
  @backstage/plugin-proxy-backend                  0.2.37
  @backstage/plugin-scaffolder-backend             1.12.0
  @backstage/plugin-scaffolder-common              1.2.6
  @backstage/plugin-scaffolder-node                0.1.1
  @backstage/plugin-scaffolder-react               1.2.0
  @backstage/plugin-scaffolder                     1.12.0
  @backstage/plugin-search-backend-module-pg       0.5.4
  @backstage/plugin-search-backend-node            1.1.4
  @backstage/plugin-search-backend                 1.2.4
  @backstage/plugin-search-common                  1.2.1, 1.2.2
  @backstage/plugin-search-react                   1.4.0, 1.5.1
  @backstage/plugin-search                         1.1.1
  @backstage/plugin-stack-overflow                 0.1.10
  @backstage/plugin-tech-radar                     0.6.2
  @backstage/plugin-techdocs-backend               1.6.0
  @backstage/plugin-techdocs-module-addons-contrib 1.0.11
  @backstage/plugin-techdocs-node                  1.6.0
  @backstage/plugin-techdocs-react                 1.1.4
  @backstage/plugin-techdocs                       1.6.0
  @backstage/plugin-user-settings                  0.7.1
  @backstage/release-manifests                     0.0.9
  @backstage/test-utils                            1.2.6
  @backstage/theme                                 0.2.16, 0.2.18
  @backstage/types                                 1.0.2
  @backstage/version-bridge                        1.0.3
Done in 0.43s.

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

• [X] I checked and didn't find similar issue

🏢 Have you read the Code of Conduct?

• [X] I have read the Code of Conduct

Are you willing to submit PR?

No, I don't have time to work on this right now

[kichristensen]

I had the same issue it was because it was blocked by CSP (Content-Security-Policies). You can look in your browsers developer tools to see if the same happens in your case.

Adding the following configuration to app-config.yaml solved it for me:

backend:
  csp:
    img-src: ["'self'", 'https://kroki.io/']

[saheljalal]

Hi @kichristensen thanks for the input. My config is currently set with the following which I think is more permissive:

  csp:
    connect-src: ['self', 'http:', 'https:']
    img-src: ['self', 'http:', 'https:', 'data:']

But the URL link generation is what struck me as wrong since it includes None like a python failure. The images do get generated but are located a directory above so I think something feels wrong with the link generation and not sure who is responsible for wiring things up 🤷 .

[benjdlambert]

@saheljalal do you think that this could be mkdocs issue? @kichristensen could you share your mkdocs setup and version numbers etc?

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[sp71]

Also facing issue

[saheljalal]

So I solved this issue with this workaround. By adding an empty site_url it appears to fix the issue so maybe this can be closed out?

[saheljalal]

@benjdlambert Seems like this is a plugin issue for mkdocs and kroki. Not sure how they will fix but I was able to fix it with workaround above ☝️

[freben]

Alright, closing as there is a workaround!