docs: add private registry documentation

compose.yaml

@@ -72,6 +72,8 @@ services:
       - ./configs:/opt/app-root/src/configs:z
       - dynamic-plugins-root:/dynamic-plugins-root
       - extensions-catalog:${CATALOG_ENTITIES_EXTRACT_DIR:-/extensions}
+      # Registry auth for private OCI registries (set REGISTRY_AUTH_FILE_PATH in .env)
+      - ${REGISTRY_AUTH_FILE_PATH:-./configs/extra-files/templates/placeholder.json}:/opt/app-root/src/.config/containers/auth.json:ro,Z
 
   # RAG initialization service: Copies RAG embeddings and vector database to shared volumes
   # This runs once at startup to prepare the RAG data for the lightspeed-core container

configs/extra-files/templates/placeholder.json

@@ -1 +1 @@
-{}
+{}

default.env

@@ -63,6 +63,13 @@ SEGMENT_WRITE_KEY=gGVM6sYRK0D0ndVX22BOtS7NRcxPej8t
 # See the compose-with-corporate-proxy.yaml file.
 #NO_PROXY=localhost,127.0.0.1
 
+# Path to your local container registry auth file (from podman login / docker login)
+# Common locations:
+#   Podman: ~/.config/containers/auth.json (or $XDG_RUNTIME_DIR/containers/auth.json)
+#   Docker: ~/.docker/config.json
+# See docs/rhdh-local-guide/container-image-guide.md for details.
+#REGISTRY_AUTH_FILE_PATH=
+
 # ==============================================================================
 # Developer Lightspeed Configuration
 # ==============================================================================

docs/rhdh-local-guide/container-image-guide.md

@@ -1,12 +1,43 @@
 ## Configuring registry credentials
 
-Place your registry credentials in `./configs/extra-files`, then reference the auth file in your `.env`:
+If you need to pull RHDH images or install dynamic plugins from private OCI registries (such as `registry.redhat.io`), you need to configure registry authentication. There are two options:
+
+### Option A: Mount host credentials directly (recommended)
+
+If you already have credentials on your host (from `podman login` or `docker login`), point `REGISTRY_AUTH_FILE_PATH` in your `.env` to that file:
+
+```bash
+# Podman (Linux)
+REGISTRY_AUTH_FILE_PATH=${XDG_RUNTIME_DIR}/containers/auth.json
+
+# Podman (macOS) or when XDG_RUNTIME_DIR is not set
+REGISTRY_AUTH_FILE_PATH=~/.config/containers/auth.json
+
+# Docker
+REGISTRY_AUTH_FILE_PATH=~/.docker/config.json
+```
+
+The auth file is bind-mounted into the `install-dynamic-plugins` container automatically. When the file contains valid credentials, `REGISTRY_AUTH_FILE` is set internally — no additional configuration needed.
+
+If you haven't logged in yet, do so first:
+
+```bash
+podman login registry.redhat.io
+```
+
+### Option B: Copy credentials into the project
+
+Copy your registry credentials file into `./configs/extra-files/`, then set the `REGISTRY_AUTH_FILE` variable in your `.env`:
+
+```bash
+cp ~/.config/containers/auth.json ./configs/extra-files/auth.json
+```
 
 ```bash
 REGISTRY_AUTH_FILE=/opt/app-root/src/configs/extra-files/auth.json
 ```
 
-This allows RHDH-local to pull OCI artifacts from registries like registry.redhat.io without authentication errors.
+This works because the `configs/` directory is already mounted into the container. Files in `configs/extra-files/` are gitignored, so your credentials will not be committed.
 
 ## Changing the container image
 

prepare-and-install-dynamic-plugins.sh

@@ -51,6 +51,15 @@
     echo "No .npmrc found, skipping NPM_CONFIG_USERCONFIG"
 fi
 
+# If a registry auth file was mounted (not the placeholder), set REGISTRY_AUTH_FILE
+REGISTRY_AUTH_PATH="/opt/app-root/src/.config/containers/auth.json"
+if [ -z "${REGISTRY_AUTH_FILE:-}" ] && [ -f "$REGISTRY_AUTH_PATH" ] && [ "$(cat "$REGISTRY_AUTH_PATH")" != "{}" ]; then
+    echo "Found registry auth file, setting REGISTRY_AUTH_FILE"
+    export REGISTRY_AUTH_FILE="$REGISTRY_AUTH_PATH"
+else
+    echo "No registry auth file mounted, skipping REGISTRY_AUTH_FILE"
+fi
+
 DYNAMIC_PLUGINS_EXTENSIONS_FILE="/dynamic-plugins-root/dynamic-plugins.extensions.yaml"
 if [ ! -f "$DYNAMIC_PLUGINS_EXTENSIONS_FILE" ]; then
     echo "$DYNAMIC_PLUGINS_EXTENSIONS_FILE does not exist - creating it to enable dynamic plugins installation by using Extensions..."