feat(update): Introduce user-specific config files to prevent merge conflicts

.gitignore

@@ -1,3 +1,17 @@
 .env
 configs/github-app-credentials.yaml
-/tmp
+/tmp
+
+# User-specific local configuration files
+*.local.yaml
+*-credentials.yaml
+/configs/dynamic-plugins/dynamic-plugins.override.yaml
+
+# Extra-files
+/configs/extra-files/*
+!/configs/extra-files/github-app-credentials.example.yaml
+
+# Kept for backward compatibility, but now Git-ignored
+/configs/app-config.local.yaml
+/configs/dynamic-plugins.yaml
+/configs/github-app-credentials.example.yaml

README.md

@@ -35,11 +35,35 @@ To use RHDH Local you'll need a few things:
 1. (Optional) You can create a local `.env` file and override any of the default variables defined in the [`default.env`](./default.env) file provided. You can also add additional variables.
    In most cases, when you don't need GitHub Auth or testing different releases, you can skip this step, and it should work.
 
-1. (Optional) Update `configs/app-config.local.yaml`.
+1. (Optional) Create local configuration overrides.
+
+   RHDH Local supports user-specific configuration overrides using a structured `configs/` directory. You do not need to modify default files. However, if you want to customize your setup:
+
+   - Add your app config overrides to: `configs/app-config/app-config.local.yaml`
+      > You can use the included `.example.yaml` files to get started quickly:
+      >
+      > ```sh
+      > cp configs/app-config/app-config.local.example.yaml configs/app-config/app-config.local.yaml
+      > cp configs/dynamic-plugins/dynamic-plugins.override.example.yaml configs/dynamic-plugins/dynamic-plugins.override.yaml
+      > ```
+
+   - Add your plugin config overrides to:  
+     `configs/dynamic-plugins/dynamic-plugins.override.yaml`
+     > The override file must start with:
+     > ```yaml
+     > includes:
+     >   - dynamic-plugins.default.yaml
+     > ```
+     > This ensures the base plugin list is preserved and extended, rather than replaced.
+
+   - Add any extra files (like GitHub credentials) to: `configs/extra-files/`
+
+   If present, these files will be automatically loaded by the system on startup.
+
    If you need features that fetch files from GitHub you should configure `integrations.github`.
    The recommended way is to use GitHub Apps. You can find hints on how to configure it in [github-app-credentials.example.yaml](configs/github-app-credentials.example.yaml) or a more detailed instruction in [Backstage documentation](https://backstage.io/docs/integrations/github/github-apps).
 
-1. Start RHDH Local.
+2. Start RHDH Local.
    This repository should work with either `docker compose` using Docker Engine or `podman-compose` using Podman. When using Podman there are some exceptions. Check [Known Issues when using Podman Compose](#known-issues-when-using-podman-compose) for more info.
 
    ```sh
@@ -69,14 +93,22 @@ podman-compose stop rhdh && podman-compose start rhdh
 
 ## Loading dynamic plugins from a local directory
 
-During boot the `install-dynamic-plugins` container reads the contents of the `configs/dynamic-plugins.yaml` file and activates, configures, or downloads any plugins contained in that file. In addition, the `local-plugins` directory is mounted into the `install-dynamic-plugins` container on the path `/opt/app-root/src/local-plugins`. Any plugins in that location can also be activated and configured in the same way (without downloading).
+During boot, the `install-dynamic-plugins` container reads the contents of the plugin configuration file and activates, configures, or downloads any plugins listed. RHDH Local supports two ways of specifying dynamic plugin configuration:
+
+1. Default path: `configs/dynamic-plugins/dynamic-plugins.yaml`
+
+1. User override path: `configs/dynamic-plugins/dynamic-plugins.override.yaml` or `configs/dynamic-plugins.yaml` If present, this file will automatically override the default and be used by the `install-dynamic-plugins` container. `configs/dynamic-plugins/dynamic-plugins.override.yaml` takes precedence over `configs/dynamic-plugins.yaml`.
+
+In addition, the `local-plugins` directory is mounted into the `install-dynamic-plugins` container at `/opt/app-root/src/local-plugins`. Any plugins placed there can be activated/configured the same way (without downloading).
 
-You can use the `local-plugins` folder install dynamic plugins directly from your local machine using the following steps:
+To load dynamic plugins from your local machine:
 
 1. Copy the dynamic plugin binary file into the `local-plugins` directory.
-2. Make sure that the permissions are set to allow container to read files (quick and dirty solution is `chmod -R 777 local-plugins`)
-3. Configure your dynamic plugin in `dynamic-plugins.yaml`. See commented out examples in that file for examples.
-4. See [Changing Your Configuration](#changing-your-configuration) section for more information about how to change and load new configuration.
+2. Make sure permissions allow the container to read the files (e.g. `chmod -R 777 local-plugins` for quick testing).
+3. Configure your plugin in one of the supported config files:
+    - Prefer `configs/dynamic-plugins/dynamic-plugins.override.yaml` for local user overrides.
+    - If no override file is present, `configs/dynamic-plugins/dynamic-plugins.yaml` will be used.
+4. See [Changing Your Configuration](#changing-your-configuration) for more on updating and reloading configs.
 
 ## Changing The Container Image
 

compose.yaml

@@ -35,6 +35,7 @@ services:
     ports: # dclint disable-line no-unbound-port-interfaces
       - "7007:7007"
     volumes:
+      - ./configs:/opt/app-root/src/configs:Z
       - type: bind
         source: "./wait-for-plugins.sh"
         target: "/opt/app-root/src/wait-for-plugins.sh"
@@ -85,11 +86,6 @@ services:
         target: "/opt/app-root/src/configs"
         bind:
           selinux: "Z"
-      - type: bind
-        source: "./configs/dynamic-plugins.yaml"
-        target: "/opt/app-root/src/dynamic-plugins.yaml"
-        bind:
-          selinux: "Z"
       - type: volume
         source: dynamic-plugins-root
         target: /dynamic-plugins-root

configs/app-config/app-config.local.example.yaml

@@ -0,0 +1,8 @@
+# Copy this file to app-config.local.yaml to override default app settings.
+# Example with GitHub integration referencing external secrets file.
+
+integrations:
+  github:
+    - host: github.com
+      apps:
+        - $include: ../extra-files/github-app-credentials.yaml

configs/app-config.local.yaml → configs/app-config/app-config.yaml

@@ -1,3 +1,4 @@
+# This is the default rhdh-local config, and any user configuration should be added app-config.local.yaml instead
 auth:
   environment: development
   providers:

configs/dynamic-plugins/dynamic-plugins.override.example.yaml

@@ -0,0 +1,13 @@
+# Example dynamic plugin override config.
+# Copy to dynamic-plugins.override.yaml to activate local plugins.
+
+includes:
+  - dynamic-plugins.default.yaml
+
+# Below you can add custom dynamic plugins, including local ones.
+plugins:
+  - package: local-plugins/example-plugin
+    disabled: false
+    pluginConfig:
+      # Optional: Configuration passed to your plugin
+      message: "Hello from local plugin"

configs/dynamic-plugins.yaml → configs/dynamic-plugins/dynamic-plugins.yaml

@@ -1,3 +1,4 @@
+# This is the default dynamic plugins config, and any user configuration should be added dynamic-plugins.override.yaml instead
 includes:
   - dynamic-plugins.default.yaml
 plugins: []

configs/extra-files/github-app-credentials.example.yaml

@@ -0,0 +1,13 @@
+# This file defines GitHub App credentials used by Backstage/RHDH.
+# It is included from app-config.local.yaml using:
+# $include: ../extra-files/github-app-credentials.yaml
+#
+# You can generate the values using:
+#   npx @backstage/cli create-github-app <github-org-name>
+# Then rename this file to github-app-credentials.yaml
+
+appId: ${GITHUB_APP_APP_ID}
+clientId: ${GITHUB_APP_CLIENT_ID}
+clientSecret: ${GITHUB_APP_CLIENT_SECRET}
+webhookSecret: ${GITHUB_APP_WEBHOOK_SECRET}
+privateKey: ${GITHUB_APP_PRIVATE_KEY}

fixes.sh

@@ -19,5 +19,21 @@ fi
 echo "Removing ~/.npmrc to fix RHIDP-4410"
 rm -rf ~/.npmrc
 
+# handle dynamic-plugins config override
+DYNAMIC_PLUGINS_DEFAULT="/opt/app-root/src/configs/dynamic-plugins/dynamic-plugins.yaml"
+DYNAMIC_PLUGINS_OVERRIDE="/opt/app-root/src/configs/dynamic-plugins/dynamic-plugins.override.yaml"
+LINK_TARGET="/opt/app-root/src/dynamic-plugins.yaml"
+
+if [ -f "$DYNAMIC_PLUGINS_OVERRIDE" ]; then
+    echo "Using dynamic-plugins.override.yaml"
+    ln -sf "$DYNAMIC_PLUGINS_OVERRIDE" "$LINK_TARGET"
+elif [ -f "/opt/app-root/src/configs/dynamic-plugins.yaml" ]; then
+    echo "[warn] Using legacy dynamic-plugins.yaml. This method is deprecated. You can override the dynamic plugins configuration by renaming your file into configs/dynamic-plugins/dynamic-plugins.override.yaml"
+    ln -sf "/opt/app-root/src/configs/dynamic-plugins.yaml" "$LINK_TARGET"
+else
+    echo "Using default dynamic-plugins.yaml"
+    ln -sf "$DYNAMIC_PLUGINS_DEFAULT" "$LINK_TARGET"
+fi
+
 echo "Running install-dynamic-plugins.sh"
 ./install-dynamic-plugins.sh /dynamic-plugins-root

wait-for-plugins.sh

@@ -3,17 +3,29 @@
 # This script is a workaround for podman-compose absence of support for depends_on
 
 DYNAMIC_PLUGINS_CONFIG="dynamic-plugins-root/app-config.dynamic-plugins.yaml"
+USER_APP_CONFIG="configs/app-config/app-config.local.yaml"
+DEFAULT_APP_CONFIG="configs/app-config/app-config.yaml"
 
-
+# Wait for dynamic plugins config to be generated
 while [ ! -f "$DYNAMIC_PLUGINS_CONFIG" ]; do
     echo "Waiting for $DYNAMIC_PLUGINS_CONFIG to be created by install-dynamic-plugins container ..."
-    sleep 2 
+    sleep 2
 done
 
+# Optionally include user app-config.local.yaml if it exists
+EXTRA_CLI_ARGS=""
+if [ -f "$USER_APP_CONFIG" ]; then
+    echo "Using user app-config.local.yaml"
+    EXTRA_CLI_ARGS="--config $USER_APP_CONFIG"
+elif [ -f "configs/app-config.local.yaml" ]; then
+    echo "[warn] Using legacy app-config.local.yaml. This method is deprecated. You should move your local app-config file under configs/app-config/app-config.local.yaml and extra files under configs/extra-files."
+    EXTRA_CLI_ARGS="--config configs/app-config.local.yaml"
+fi
 
+# Run Backstage with default + optional config overrides
 node packages/backend --no-node-snapshot \
-    --config app-config.yaml \
+    --config "app-config.yaml" \
     --config app-config.example.yaml \
     --config app-config.example.production.yaml \
-    --config $DYNAMIC_PLUGINS_CONFIG \
-    --config configs/app-config.local.yaml 
+    --config "$DYNAMIC_PLUGINS_CONFIG" \
+    --config "$DEFAULT_APP_CONFIG" $EXTRA_CLI_ARGS