docs: add private registry documentation

[kadel]

Description

Add documentation describing how to access plugins in private container/oci registries

PR acceptance criteria

• Tests updated and passing
• Documentation updated
• Built-in TechDocs updated if needed. Note that TechDocs changes may need to be reviewed by a Product Manager and/or Architect to ensure content accuracy, clarity, and alignment with user needs.

How to test changes / Special notes to the reviewer

[rhdh-qodo-merge]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 1 🔵⚪⚪⚪⚪

🔒 Security concerns Sensitive information exposure: The added docs recommend bind-mounting auth.json/config.json, which can contain registry credentials/tokens. This increases the risk of accidental exposure (e.g., if the container is compromised, logs/debugging copies the file, or the mount is writable). Consider updating the example to mount read-only (e.g., ...:/opt/app-root/src/.config/containers/auth.json:ro,Z) and adding an explicit warning to treat the file as secret and avoid copying it into images or committing it to the repo.

⚡ Recommended focus areas for review Credentials Safety The documentation instructs mounting the local registry credentials file into the container; consider recommending a read-only mount and adding a caution that the file contains sensitive credentials and must not be committed/shared. Also verify the chosen in-container path matches what the installer expects. ## Accessing Private Container Registries If you need to install dynamic plugins from private container registries, you can mount your local container credentials into the `install-dynamic-plugins` service. This allows the plugin installer to authenticate with private registries using the credentials you already have configured on your system. Add the following volume to the `install-dynamic-plugins` service in `compose.yaml`: ```yaml install-dynamic-plugins: volumes: # ... existing volumes ... - ~/.config/containers/auth.json:/opt/app-root/src/.config/containers/auth.json:Z This mounts your local auth.json file (which contains credentials for container registries like registry.redhat.io, quay.io, etc.) into the container. The credentials are typically created when you run podman login or docker login. NOTE: The location of auth.json may vary depending on your system configuration. Common locations include: ~/.config/containers/auth.json (Podman default) ~/.docker/config.json (Docker default) Adjust the source path accordingly based on your container runtime. </details> <details><summary><a href='https://github.com/redhat-developer/rhdh-local/pull/151/files#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R125-R142'><strong>Cross-Platform Notes</strong></a> The example uses a Linux/Podman-style path; consider briefly noting platform differences (e.g., macOS/Windows, rootless vs root) and that SELinux relabeling is only relevant on SELinux-enabled hosts. </summary> ```markdown Add the following volume to the `install-dynamic-plugins` service in `compose.yaml`: ```yaml install-dynamic-plugins: volumes: # ... existing volumes ... - ~/.config/containers/auth.json:/opt/app-root/src/.config/containers/auth.json:Z This mounts your local auth.json file (which contains credentials for container registries like registry.redhat.io, quay.io, etc.) into the container. The credentials are typically created when you run podman login or docker login. NOTE: The location of auth.json may vary depending on your system configuration. Common locations include: ~/.config/containers/auth.json (Podman default) ~/.docker/config.json (Docker default) Adjust the source path accordingly based on your container runtime. </details> </td></tr> <tr><td>📚&nbsp;<strong>Focus areas based on broader codebase context</strong><br><br> <details><summary><a href='https://github.com/redhat-developer/rhdh-local/pull/151/files#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R121-R142'><strong>Docs Alignment</strong></a> The new guidance recommends mounting a local `auth.json` from the host into `install-dynamic-plugins`, but related docs in the ecosystem describe providing registry credentials via Kubernetes Secrets (and reference official RHDH docs). Consider clarifying that this is a *docker-compose/local* approach and adding a short pointer or alternative steps for cluster deployments to avoid readers applying the host-mount pattern in OpenShift/Kubernetes contexts. (<a href="https://github.com/redhat-developer/rhdh-local/blob/353db4e/docs/catalog-index-configuration.md/#L16-L21">Ref 1</a>, <a href="https://github.com/redhat-developer/rhdh-local/blob/bfe3d48/docs/dynamic-plugins.md/#L5-L41">Ref 8</a>) </summary> ```markdown ## Accessing Private Container Registries If you need to install dynamic plugins from private container registries, you can mount your local container credentials into the `install-dynamic-plugins` service. This allows the plugin installer to authenticate with private registries using the credentials you already have configured on your system. Add the following volume to the `install-dynamic-plugins` service in `compose.yaml`: ```yaml install-dynamic-plugins: volumes: # ... existing volumes ... - ~/.config/containers/auth.json:/opt/app-root/src/.config/containers/auth.json:Z This mounts your local auth.json file (which contains credentials for container registries like registry.redhat.io, quay.io, etc.) into the container. The credentials are typically created when you run podman login or docker login. NOTE: The location of auth.json may vary depending on your system configuration. Common locations include: ~/.config/containers/auth.json (Podman default) ~/.docker/config.json (Docker default) Adjust the source path accordingly based on your container runtime. **Reference reasoning:** Existing documentation for private registry access emphasizes supplying an `auth.json` through a named Secret and mounting it into the relevant container, and also links to the official product documentation for the supported authentication flow. Aligning this README section with that pattern (or explicitly scoping it to local compose usage and linking out) reduces ambiguity and keeps private-registry authentication guidance consistent across installation types. </details> </td></tr> <tr><td> <details><summary>📄 References</summary><ol><li><a href="https://github.com/redhat-developer/rhdh-local/blob/353db4e/docs/catalog-index-configuration.md/#L16-L21">redhat-developer/rhdh-chart/docs/catalog-index-configuration.md [16-21]</a></li> <li><a href="https://github.com/redhat-developer/rhdh-local/blob/353db4e/docs/catalog-index-configuration.md/#L1-L15">redhat-developer/rhdh-chart/docs/catalog-index-configuration.md [1-15]</a></li> <li><a href="https://github.com/redhat-developer/rhdh-local/blob/353db4e/charts/backstage/README.md/#L304-L309">redhat-developer/rhdh-chart/charts/backstage/README.md [304-309]</a></li> <li><a href="https://github.com/redhat-developer/rhdh-local/blob/bfe3d48/docs/dynamic-plugins.md/#L46-L52">redhat-developer/rhdh-operator/docs/dynamic-plugins.md [46-52]</a></li> <li><a href="https://github.com/redhat-developer/rhdh-local/blob/bfe3d48/docs/dynamic-plugins.md/#L42-L45">redhat-developer/rhdh-operator/docs/dynamic-plugins.md [42-45]</a></li> <li><a href="https://github.com/redhat-developer/rhdh-local/blob/bfe3d48/docs/dynamic-plugins.md/#L1-L4">redhat-developer/rhdh-operator/docs/dynamic-plugins.md [1-4]</a></li> <li><a href="https://github.com/redhat-developer/rhdh-local/blob/516d216/docs/orchestrator-cicd.md/#L103-L123">redhat-developer/rhdh-operator/docs/orchestrator-cicd.md [103-123]</a></li> <li><a href="https://github.com/redhat-developer/rhdh-local/blob/bfe3d48/docs/dynamic-plugins.md/#L5-L41">redhat-developer/rhdh-operator/docs/dynamic-plugins.md [5-41]</a></li> </ol></details> </td></tr> </table>

[rhdh-qodo-merge]

PR Type

Documentation

---

Description

• Add comprehensive guide for accessing private container registries

• Document volume mounting configuration for install-dynamic-plugins service

• Provide common auth.json file locations for Podman and Docker

• Include notes on credential setup via podman/docker login

---

File Walkthrough

	Relevant files
Documentation	README.md Document private registry credential mounting setup            README.md Added new section "Accessing Private Container Registries" with setup instructions Documented volume mount configuration for ~/.config/containers/auth.json Listed common auth.json file locations for different container runtimes Included note about credential creation via podman/docker login commands +22/-0

---

[rhdh-qodo-merge]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Use an override file for compose configuration Instead of advising users to modify compose.yaml directly, the documentation should recommend using a compose.override.yaml file. This prevents merge conflicts and aligns with standard practices for local configuration. Examples: README.md [125-132] Add the following volume to the `install-dynamic-plugins` service in `compose.yaml`: ```yaml install-dynamic-plugins: volumes: # ... existing volumes ... - ~/.config/containers/auth.json:/opt/app-root/src/.config/containers/auth.json:Z </details> ### Solution Walkthrough: #### Before: ```markdown # In README.md Add the following volume to the `install-dynamic-plugins` service in `compose.yaml`: ```yaml install-dynamic-plugins: volumes: # ... existing volumes ... - ~/.config/containers/auth.json:/opt/app-root/src/.config/containers/auth.json:Z #### After: ```markdown # In README.md Add the following volume to the `install-dynamic-plugins` service by creating a `compose.override.yaml` file: ```yaml # compose.override.yaml services: install-dynamic-plugins: volumes: - ~/.config/containers/auth.json:/opt/app-root/src/.config/containers/auth.json:Z <details><summary>Suggestion importance[1-10]: 8</summary> __ Why: The suggestion correctly identifies that modifying `compose.yaml` can cause future merge conflicts and proposes using `compose.override.yaml`, which is a best practice that improves maintainability for users. </details></details></td><td align=center>Medium </td></tr><tr><td rowspan=1>General</td> <td> <details><summary>Clarify instructions for different runtimes</summary> ___ **Clarify the documentation by providing separate, explicit configuration examples <br>for both Podman and Docker users to avoid misconfiguration when accessing <br>private container registries.** [README.md [125-141]](https://github.com/redhat-developer/rhdh-local/pull/151/files#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R125-R141) ```diff -Add the following volume to the `install-dynamic-plugins` service in `compose.yaml`: +Add the following volume to the `install-dynamic-plugins` service in `compose.yaml`, depending on your container runtime. + +**For Podman users:** + +Mount your `auth.json` file: ```yaml install-dynamic-plugins: volumes: # ... existing volumes ... - ~/.config/containers/auth.json:/opt/app-root/src/.config/containers/auth.json:Z -This mounts your local auth.json file (which contains credentials for container registries like registry.redhat.io, quay.io, etc.) into the container. The credentials are typically created when you run podman login or docker login. +For Docker users: -> NOTE: The location of auth.json may vary depending on your system configuration. Common locations include: -> -> - ~/.config/containers/auth.json (Podman default) -> - ~/.docker/config.json (Docker default) -> -> Adjust the source path accordingly based on your container runtime. +Mount your config.json file. Note that the destination path inside the container still uses auth.json. +```yaml +install-dynamic-plugins: volumes: ... existing volumes ... ~/.docker/config.json:/opt/app-root/src/.config/containers/auth.json:Z +``` +This mounts your local container credentials file into the container, which is typically created when you run podman login or docker login. The tools inside the container will then use these credentials to pull images from private registries. + `[To ensure code accuracy, apply this suggestion manually]` <details><summary>Suggestion importance[1-10]: 6</summary> __ Why: The suggestion correctly identifies a point of confusion in the documentation and provides a much clearer, less error-prone example for both Podman and Docker users. </details></details></td><td align=center>Low </td></tr> <tr><td align="center" colspan="2"> - [ ] Update <!-- /improve_multi --more_suggestions=true --> </td><td></td></tr></tbody></table>

[Fortune-Ndlovu]

I wonder if we should move this to the already existing https://github.com/redhat-developer/rhdh-local/blob/main/docs/rhdh-local-guide/container-image-guide.md because the existing REGISTRY_AUTH_FILE approach seems to be correct however, using existing local credentials without copying is also valid. I'd suggest extending the existing docs in container-image-guide.md to show both options, wdyt?

[rm3l]

So this requires modifying a version-controlled file, which I believe we are striving to avoid as much as possible for users.

Not tested, but I wonder if we could not actually add this by default as a configurable bind mount in the current compose.yaml:

install-dynamic-plugins:
  volumes:
    # ... existing volumes ...
    - ${REGISTRY_AUTH_FILE_PATH:-./configs/registry-auth.example.json}:/opt/app-root/src/.config/containers/auth.example.json:Z

Adding a default value to mount an example empty auth file, so that this is optional.
But assuming skopeo will fail if the auth.json file is not valid json, I guess we can maybe do some special handling in the prepare-and-install-dynamic-plugins.sh script to copy /opt/app-root/src/.config/containers/auth.example.json to /opt/app-root/src/.config/containers/auth.json if REGISTRY_AUTH_FILE_PATH is set in the env.

With this, users would only need to set the REGISTRY_AUTH_FILE_PATH in their local .env file.
WDYT?

[rm3l]

I believe the default value for Podman is ${XDG_RUNTIME_DIR:-~/.config}/containers/auth.json (at least on Linux): https://docs.podman.io/en/latest/markdown/podman-login.1.html#description