From 5bcdc91d12aeab8e8e017a00e3950ca412337f20 Mon Sep 17 00:00:00 2001
From: Frank Kong <frkong@redhat.com>
Date: Fri, 7 Nov 2025 12:53:46 -0500
Subject: [PATCH 1/2] docs: refactor docs to prioritize container execution

Signed-off-by: Frank Kong <frkong@redhat.com>
---
 .dockerignore                             |  13 +-
 CONTRIBUTING.md                           | 467 ++++++++++++++++++++++
 README.md                                 | 458 ++++++---------------
 examples/example-config-aws-ecs/README.md | 170 ++++++++
 examples/example-config-gitlab/README.md  | 128 ++++++
 examples/example-config-todo/README.md    | 186 +++++++++
 6 files changed, 1087 insertions(+), 335 deletions(-)
 create mode 100644 CONTRIBUTING.md
 create mode 100644 examples/example-config-aws-ecs/README.md
 create mode 100644 examples/example-config-gitlab/README.md
 create mode 100644 examples/example-config-todo/README.md

diff --git a/.dockerignore b/.dockerignore
index 848ca72..8be10a4 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -1,17 +1,26 @@
+# Local Configuration Folders
 config/
 outputs/
 workspace/
+
+# IDE 
 .vscode/
+# Git
 .git/
 .github/
 .gitignore
+# Python Virtual Environment
 .venv/
+# Cursor
 .cursor/
+# Python Caches and Test Files
 **/__pycache__/
-requirements.dev.txt
 tests/
 pytest.ini
 .pytest_cache/
 *.pyc
 htmlcov/
-.coverage
\ No newline at end of file
+.coverage
+
+# Development Dependencies
+requirements.dev.txt
\ No newline at end of file
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..39105b6
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,467 @@
+# Contributing to RHDH Dynamic Plugin Factory
+
+Thank you for your interest in contributing to the RHDH Dynamic Plugin Factory! This guide will help you get started with development, testing, and submitting contributions.
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Development Environment](#development-environment)
+- [Project Structure](#project-structure)
+- [Running Tests](#running-tests)
+- [Development Workflow](#development-workflow)
+- [Code Quality Standards](#code-quality-standards)
+- [Submitting Changes](#submitting-changes)
+
+## Getting Started
+
+### Fork and Clone
+
+1. **Fork the repository** on GitHub by clicking the "Fork" button
+
+2. **Clone your fork** locally:
+
+```bash
+git clone https://github.com/YOUR_USERNAME/rhdh-dynamic-plugin-factory
+cd rhdh-dynamic-plugin-factory
+```
+
+**3. Add the upstream remote:**
+
+```bash
+git remote add upstream https://github.com/redhat-developer/rhdh-dynamic-plugin-factory
+```
+
+### Choose Your Development Environment
+
+You can develop using either containers or local setup.
+
+## Development Environment
+
+### Option 1: Container-Based Development
+
+Container-based development provides consistency and isolation.
+
+#### Prerequisites
+
+- Podman installed ([installation guide](https://podman.io/getting-started/installation))
+- Podman Machine initialized (macOS/Windows):
+
+  ```bash
+  podman machine init
+  podman machine start
+  ```
+
+#### Building the Development Image
+
+```bash
+podman build -t rhdh-dynamic-plugin-factory:dev .
+```
+
+#### Testing Your Changes
+
+Run the factory with your local build:
+
+```bash
+podman run --rm -it \
+  --device /dev/fuse \
+  -v ./config:/config:z \
+  -v ./workspace:/workspace:z \
+  -v ./outputs:/outputs:z \
+  rhdh-dynamic-plugin-factory:dev \
+  --workspace-path workspaces/todo \
+  --no-push-images
+```
+
+Follow instructions in the main [Usage Docs](./README.md) for container usage and replace image with your locally built image.
+
+### Option 2: Local Development Setup
+
+#### Requirements
+
+- **Python**: 3.8 or higher
+- **Node.js**: 22 or higher (version specified in `default.env`)
+- **Corepack**: To configure the yarn package managers on a project to project basis
+- **Git**: For cloning repositories
+- **Buildah**: Required for building and pushing container images
+  - Linux: `dnf install buildah` or `apt install buildah`
+  - macOS: Not directly supported (use Podman containers)
+  - Windows: Not directly supported (use Podman containers)
+
+#### Virtual Environment Setup
+
+Create and activate a Python virtual environment:
+
+```bash
+python -m venv venv
+source venv/bin/activate
+```
+
+#### Install Dependencies
+
+```bash
+# Install Python dependencies
+pip install -r requirements.txt -r requirements.dev.txt
+```
+
+#### Environment Configuration
+
+The `default.env` file contains default settings:
+
+```bash
+# View current settings
+cat default.env
+
+# Create a custom .env file (optional)
+cp default.env .env
+```
+
+#### Verify Setup
+
+Test that the CLI works:
+
+```bash
+python -m src.rhdh_dynamic_plugin_factory --help
+```
+
+### Local Execution Examples
+
+Once you have the local environment set up, you can run the factory directly with Python.
+
+#### Build plugins and save outputs locally
+
+```bash
+python -m src.rhdh_dynamic_plugin_factory \
+  --config-dir ./config \
+  --workspace-path workspaces/todo \
+  --output-dir ./outputs
+```
+
+#### Build and push to registry
+
+Create a `./config/.env` file with your registry credentials:
+
+```bash
+REGISTRY_URL=quay.io
+REGISTRY_USERNAME=myuser
+REGISTRY_PASSWORD=mytoken
+REGISTRY_NAMESPACE=mynamespace
+```
+
+Then run:
+
+```bash
+python -m src.rhdh_dynamic_plugin_factory \
+  --config-dir ./config \
+  --workspace-path workspaces/announcements \
+  --push-images
+```
+
+The factory will automatically read the registry credentials from `./config/.env`.
+
+#### Using a local repository (skip cloning)
+
+```bash
+python -m src.rhdh_dynamic_plugin_factory \
+  --config-dir ./config \
+  --repo-path ./existing-workspace \
+  --workspace-path . \
+  --output-dir ./outputs \
+  --use-local
+```
+
+## Project Structure
+
+```bash
+rhdh-dynamic-plugin-factory/
+├── src/rhdh_dynamic_plugin_factory/
+│   ├── __init__.py              # Package initialization
+│   ├── __main__.py              # Package entry point
+│   ├── cli.py                   # CLI implementation and argument parsing
+│   ├── config.py                # Configuration classes and validation
+│   ├── logger.py                # Logging setup and utilities
+│   └── utils.py                 # Utility functions
+├── scripts/
+│   ├── export-workspace.sh      # Plugin export script (called by CLI)
+│   └── override-sources.sh      # Patch/overlay application script
+├── tests/
+│   ├── __init__.py
+│   ├── conftest.py              # Pytest fixtures and configuration
+│   ├── test_config.py           # Configuration tests
+│   ├── test_plugin_list_config.py  # Plugin list parsing tests
+│   └── test_source_config.py    # Source configuration tests
+├── examples/                    # Example configuration sets
+│   ├── example-config-todo/
+│   ├── example-config-gitlab/
+│   └── example-config-aws-ecs/
+├── .cursor/rules/               # Development guidelines
+│   ├── commit-standards.mdc
+│   ├── documentation-standards.mdc
+│   ├── planning-process.mdc
+│   ├── python-code-quality.mdc
+│   └── shell-code-quality.mdc
+├── default.env                  # Default environment settings
+├── Dockerfile                   # Container image definition
+├── requirements.txt             # Python runtime dependencies
+├── requirements.dev.txt         # Python development dependencies
+├── pytest.ini                   # Pytest configuration
+└── README.md                    # User documentation
+```
+
+### Key Components
+
+- **`cli.py`**: Handles command-line arguments, orchestrates the build process
+- **`config.py`**: Loads and validates configuration from files and environment
+- **`logger.py`**: Configures structured logging with color output
+- **`utils.py`**: Helper functions for file operations, subprocess execution
+- **`export-workspace.sh`**: Shell script that calls the RHDH CLI to export plugins
+- **`override-sources.sh`**: Applies patches and overlays to source code
+
+## Running Tests
+
+The project uses pytest for testing.
+
+### Run All Tests
+
+```bash
+pytest tests/
+```
+
+### Run Tests with Verbose Output
+
+```bash
+pytest tests/ -v
+```
+
+### Run Tests for a Specific Module
+
+```bash
+pytest tests/test_config.py -v
+```
+
+### Run a Specific Test Class or Method
+
+```bash
+# Run a specific test class
+pytest tests/test_config.py::TestPluginFactoryConfigLoadFromEnv -v
+
+# Run a specific test method
+pytest tests/test_config.py::TestPluginFactoryConfigLoadFromEnv::test_load_from_env_valid_configuration -v
+```
+
+### Run with Coverage Reporting
+
+```bash
+pytest tests/ --cov=src/rhdh_dynamic_plugin_factory --cov-report=term-missing
+```
+
+This will show which lines of code are not covered by tests.
+
+### Run Tests in Watch Mode
+
+For active development, you can use pytest-watch:
+
+```bash
+pip install pytest-watch
+ptw tests/
+```
+
+### Writing Tests
+
+When adding new features:
+
+1. **Write tests first** (Test-Driven Development)
+2. **Test both success and failure cases**
+3. **Use descriptive test names**: `test_<what>_<condition>_<expected>`
+4. **Use fixtures** from `conftest.py` for common setup
+5. **Mock external dependencies** (file system, subprocess calls)
+
+Example test structure:
+
+```python
+def test_config_loads_from_valid_file(tmp_path):
+    """Test that configuration loads successfully from a valid file."""
+    # Arrange
+    config_file = tmp_path / "config.json"
+    config_file.write_text('{"key": "value"}')
+    
+    # Act
+    result = load_config(config_file)
+    
+    # Assert
+    assert result["key"] == "value"
+```
+
+## Development Workflow
+
+### 1. Create a Feature Branch
+
+```bash
+# Update your main branch
+git checkout main
+git pull upstream main
+
+# Create a new feature branch
+git checkout -b feature/my-new-feature
+```
+
+### 2. Make Your Changes
+
+- Write code following the [Code Quality Standards](#code-quality-standards)
+- Add or update tests
+- Update documentation if needed
+
+### 3. Run Tests and Linters
+
+```bash
+# Run tests
+pytest tests/
+
+# Check code coverage
+pytest tests/ --cov=src/rhdh_dynamic_plugin_factory --cov-report=term-missing
+
+# Format code (if using black)
+black src/ tests/
+
+# Check types (if using mypy)
+mypy src/
+```
+
+### 4. Commit Your Changes
+
+Follow the [Conventional Commits](https://www.conventionalcommits.org/) format:
+
+```bash
+git add .
+git commit -m "feat: add support for custom plugin configurations"
+```
+
+Commit types:
+
+- `feat:` New feature
+- `fix:` Bug fix
+- `docs:` Documentation changes
+- `test:` Test additions or changes
+- `refactor:` Code refactoring
+- `chore:` Maintenance tasks
+- `ci:` CI/CD changes
+
+See `.cursor/rules/commit-standards.mdc` for detailed commit guidelines.
+
+### 5. Push to Your Fork
+
+```bash
+git push origin feature/my-new-feature
+```
+
+### 6. Create a Pull Request
+
+1. Go to your fork on GitHub
+2. Click "Pull Request"
+3. Select your branch and provide a clear description:
+   - What changes were made
+   - Why they were needed
+   - Any breaking changes
+   - Related issues
+
+## Code Quality Standards
+
+### Python Code Quality
+
+Follow the guidelines in `.cursor/rules/python-code-quality.mdc`:
+
+- **PEP 8**: Follow Python style guidelines
+- **Type Hints**: Use type annotations for function signatures
+- **Docstrings**: Use Google-style docstrings for all public functions/classes
+- **Error Handling**: Use specific exception types, provide helpful error messages
+- **Imports**: Group and sort imports (stdlib, third-party, local)
+
+Example:
+
+```python
+def process_config(config_path: Path, validate: bool = True) -> Dict[str, Any]:
+    """Process and validate a configuration file.
+    
+    Args:
+        config_path: Path to the configuration file.
+        validate: Whether to validate the configuration.
+        
+    Returns:
+        Dictionary containing the processed configuration.
+        
+    Raises:
+        FileNotFoundError: If the configuration file doesn't exist.
+        ValueError: If the configuration is invalid.
+    """
+    if not config_path.exists():
+        raise FileNotFoundError(f"Configuration file not found: {config_path}")
+    
+    # Implementation here
+    pass
+```
+
+### Shell Script Quality
+
+Follow the guidelines in `.cursor/rules/shell-code-quality.mdc`:
+
+- Follow Google Shell Style Guide
+- Use `#!/usr/bin/env bash` shebang
+- Enable strict mode: `set -euo pipefail`
+- Quote all variables
+- Use functions for reusable logic
+- Add comments for complex operations
+
+### Documentation Standards
+
+Follow the guidelines in `.cursor/rules/documentation-standards.mdc`:
+
+- Use Google-style docstrings
+- Keep documentation up-to-date with code changes
+- Include examples in docstrings when helpful
+- Update README.md for user-facing changes
+- Add comments for complex logic
+
+## Submitting Changes
+
+### Pull Request Checklist
+
+Before submitting:
+
+- [ ] Tests pass locally
+- [ ] Code follows style guidelines
+- [ ] Documentation is updated
+- [ ] Commit messages follow conventional format
+- [ ] No merge conflicts with main branch
+- [ ] Changes are in a feature branch (not main)
+
+### Review Process
+
+1. Maintainers will review your PR
+2. Address any feedback or requested changes
+3. Once approved, a maintainer will merge your PR
+
+### After Your PR is Merged
+
+```bash
+# Update your local repository
+git checkout main
+git pull upstream main
+
+# Delete your feature branch (optional)
+git branch -d feature/my-new-feature
+```
+
+## Getting Help
+
+- **Issues**: Search existing [GitHub Issues](https://github.com/redhat-developer/rhdh-dynamic-plugin-factory/issues) or create a new one
+- **Discussions**: Join the conversation in [GitHub Discussions](https://github.com/redhat-developer/rhdh-dynamic-plugin-factory/discussions)
+- **Documentation**: Check the [README.md](./README.md) and example configurations
+
+## License
+
+By contributing to this project, you agree that your contributions will be licensed under the same license as the project (see [LICENSE](./LICENSE) file).
+
+## Code of Conduct
+
+This project follows a Code of Conduct to ensure an inclusive and welcoming environment for all contributors. Please be respectful and professional in all interactions.
+
+Thank you for contributing to RHDH Dynamic Plugin Factory!
diff --git a/README.md b/README.md
index 926e4c7..3d2237b 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,42 @@
 
 A comprehensive tool for building and exporting dynamic plugins for Red Hat Developer Hub (RHDH) from Backstage plugin source code.
 
+## Table of Contents
+
+- [RHDH Dynamic Plugin Factory](#rhdh-dynamic-plugin-factory)
+  - [Table of Contents](#table-of-contents)
+  - [Overview](#overview)
+  - [Installation](#installation)
+    - [Using Pre-built Container Images](#using-pre-built-container-images)
+    - [Container Requirements](#container-requirements)
+    - [Basic Container Usage](#basic-container-usage)
+    - [Running Locally Without Containers](#running-locally-without-containers)
+  - [Configuration](#configuration)
+    - [Directory Structure](#directory-structure)
+    - [Configuration Files](#configuration-files)
+      - [1. `default.env` (Provided)](#1-defaultenv-provided)
+      - [2. `config/source.json` (Required for remote repositories)](#2-configsourcejson-required-for-remote-repositories)
+      - [3. `config/plugins-list.yaml` (Required)](#3-configplugins-listyaml-required)
+      - [4. `config/.env` (Optional)](#4-configenv-optional)
+    - [Patches and Overlays](#patches-and-overlays)
+      - [Patches Directory (`config/patches/`)](#patches-directory-configpatches)
+      - [Overlays Directory (`config/<path-to-plugin-root-with-respect-to-workspace>/overlays/`)](#overlays-directory-configpath-to-plugin-root-with-respect-to-workspaceoverlays)
+  - [Usage](#usage)
+    - [Command-Line Options](#command-line-options)
+    - [Understanding Volume Mounts](#understanding-volume-mounts)
+    - [Container Usage Examples](#container-usage-examples)
+      - [Minimal example (no local files saved)](#minimal-example-no-local-files-saved)
+      - [Build plugins and save outputs locally](#build-plugins-and-save-outputs-locally)
+      - [Build and push to registry](#build-and-push-to-registry)
+      - [Using a local repository (skip cloning)](#using-a-local-repository-skip-cloning)
+  - [Output](#output)
+    - [Build Artifacts](#build-artifacts)
+    - [Container Images](#container-images)
+  - [Examples](#examples)
+    - [Quick Example: TODO Workspace](#quick-example-todo-workspace)
+  - [Local Development \& Contributing](#local-development--contributing)
+  - [Resources](#resources)
+
 ## Overview
 
 The RHDH Plugin Factory automates the process of converting Backstage plugins into RHDH dynamic plugins. It provides:
@@ -12,80 +48,35 @@ The RHDH Plugin Factory automates the process of converting Backstage plugins in
 - **Dynamic Plugin Packaging**: Build, export and package plugins using the RHDH CLI
 - **Container Image Publishing**: Optionally push to container registries (Quay, OpenShift, etc.)
 
-## Prerequisites
-
-### Local Development
-
-- **Python**: 3.8 or higher
-- **Node.js**: 22 or higher (specified in `default.env`)
-- **Yarn**: Latest version via Corepack
-- **Git**: For cloning and checking out remote git repositories
-- **Buildah**: For building and pushing container images (if using `--push-images`)
-
 ## Installation
 
-You can use the RHDH Plugin Factory either locally or via a container image.
-
-### Local Setup
-
-1. **Clone the repository**:
-
-   ```bash
-   git clone https://github.com/redhat-developer/rhdh-dynamic-plugin-factory
-   cd rhdh-dynamic-plugin-factory
-   ```
-
-2. **Install Python dependencies**:
-
-   ```bash
-   pip install -r requirements.txt -r requirements.dev.txt
-   ```
+The RHDH Plugin Factory is distributed as a pre-built container image. It is recommended to use Podman for all platforms.
 
-3. **Set up custom environment variables**:
-
-   ```bash
-   # The default.env file contains required version settings
-   # Copy and customize if needed
-   cp default.env .env
-   ```
-
-### Container Image Setup
-
-#### Using Pre-built Community Images
+### Using Pre-built Container Images
 
 Pre-built container images are published to `quay.io/rhdh-community/dynamic-plugins-factory` with tags corresponding to the version of RHDH they were designed for:
 
 ```bash
 # Pull the latest version
 podman pull quay.io/rhdh-community/dynamic-plugins-factory:latest
-
-# Or pull a specific RHDH version
-podman pull quay.io/rhdh-community/dynamic-plugins-factory:1.8
-```
-
-#### Building the Image
-
-Alternatively, you can build the container image locally using Podman or Docker:
-
-```bash
-podman build -t rhdh-dynamic-plugin-factory:latest .
 ```
 
-Or with Docker:
-
 ```bash
-docker build -t rhdh-dynamic-plugin-factory:latest .
+# Or pull a specific RHDH version
+podman pull quay.io/rhdh-community/dynamic-plugins-factory:1.8
 ```
 
-#### Container Requirements
+### Container Requirements
 
 The container requires specific capabilities and device access for building dynamic plugins:
 
-- **Volume Mounts**: Mount your configuration, workspace, and output directories to the `/config`, `/workspace` and `/outputs` directories respectively
-- **Device Access**: Mount `/dev/fuse` for filesystem operations
-- **SELinux Context**: Use `:z` flag for volume mounts on SELinux-enabled systems when using `podman`
+- **Volume Mounts**: Mount your configuration, workspace, and/or output directories to the `/config`, `/workspace` and `/outputs` directories respectively
+- **Device Access**: Mount `/dev/fuse` for filesystem operations (required for buildah)
+- **SELinux Context**: Use `:z` flag for volume mounts on SELinux-enabled systems (RHEL/Fedora/CentOS)
 
-#### Basic Container Usage
+The `--device /dev/fuse` flag passes the FUSE device from the Linux environment (native on Linux, or from Podman Machine's VM on macOS/Windows) to the container, enabling buildah operations.
+
+### Basic Container Usage
 
 ```bash
 podman run --rm -it \
@@ -94,14 +85,14 @@ podman run --rm -it \
   -v ./workspace:/workspace:z \
   -v ./outputs:/outputs:z \
   quay.io/rhdh-community/dynamic-plugins-factory:latest \
+  --workspace-path <path-to-workspace>
 ```
 
-**Key Differences from Local Usage:**
+**Note:** The `--config-dir`, `--repo-path`, and `--output-dir` options use default values of `/config`, `/workspace`, and `/outputs` respectively, which map to your local directories through volume mounts.
+
+### Running Locally Without Containers
 
-- Paths for `--config-dir`, `--repo-path`, and `--output-dir` don't need to be defined since they use the default values of `/config`, `/workspace` and `/outputs` respectively.
-- Usage of volume mounts to map your local directories to these container paths
-- The `--device /dev/fuse` flag is required for buildah operations inside the container
-- Use `:z` or `:Z` SELinux labels when running on RHEL/Fedora/CentOS systems
+For local execution without containers, see [CONTRIBUTING.md](./CONTRIBUTING.md).
 
 ## Configuration
 
@@ -111,14 +102,14 @@ The factory expects the following directory structure:
 
 ```bash
 ./
-├── config/                                   # Configuration directory (set with --config-dir)
+├── config/                                   # Configuration directory (Can be set with --config-dir)
 │   ├── .env                                  # Optional: Override environment variables
 │   ├── source.json                           # Source repository configuration
 │   ├── plugins-list.yaml                     # List of plugins to build
 │   ├── patches/                              # Optional: Patch files to apply
 │   └── <path-to-plugin-in-workspace>/overlays/   # Optional: Files to overlay on plugin source
-├── workspace/                                # Source code location (set with --repo-path)
-└── outputs/                                  # Build output directory (set with --output-dir)
+├── workspace/                                # Source code location (Can be set with --repo-path)
+└── outputs/                                  # Build output directory (Can be set with --output-dir)
 ```
 
 ### Configuration Files
@@ -129,7 +120,7 @@ This file contains required version settings and defaults for RHDH CLI:
 
 ```bash
 # Tooling versions
-RHDH_CLI_VERSION="1.7.2"
+RHDH_CLI_VERSION="1.8.0"
 ```
 
 #### 2. `config/source.json` (Required for remote repositories)
@@ -150,7 +141,7 @@ Defines the source repository to clone:
 
 #### 3. `config/plugins-list.yaml` (Required)
 
-Lists plugins to build with optional build arguments:
+A list of plugin paths (with respect to root of workspace) to plugins to build along with optional build arguments:
 
 ```yaml
 # Simple plugins (no additional arguments)
@@ -212,25 +203,23 @@ config/
 
 Patches are applied using the `override-sources.sh` script before building.
 
+See the [AWS ECS plugin example config](./examples/example-config-aws-ecs/README.md) for an example on how patches are applied
+
 #### Overlays Directory (`config/<path-to-plugin-root-with-respect-to-workspace>/overlays/`)
 
 Place files that should be copied over the source code:
 
 ```bash
 config/
-  └── plugins/
-      └── my-plugin/
-          └── overlay/
-              └── custom-config.ts
+└── plugins/
+    └── my-plugin/
+        └── overlay/
+            └── custom-config.ts
 ```
 
-## Usage
-
-### Basic Command Structure
+See the [TODO plugin example config](./examples/example-config-todo/README.md) and [Gitlab plugin example config](./examples/example-config-gitlab/README.md) for an example on using overlays.
 
-```bash
-python -m rhdh_dynamic_plugin_factory.cli [OPTIONS]
-```
+## Usage
 
 ### Command-Line Options
 
@@ -240,141 +229,100 @@ python -m rhdh_dynamic_plugin_factory.cli [OPTIONS]
 | `--repo-path` | `/workspace` | Path where plugin source code will be cloned/stored |
 | `--workspace-path` | (required) | Path to the workspace from repository root (e.g., `workspaces/todo`) |
 | `--output-dir` | `/outputs` | Directory for build artifacts (`.tgz` files and container images) |
-| `--push-images` / `--no-push-images` | `true` | Whether to push container images to registry. Defaults to not pushing if no argument is provided |
+| `--push-images` / `--no-push-images` | `--no-push-images` | Whether to push container images to registry. Defaults to not pushing if no argument is provided |
 | `--use-local` | `false` | Use local repository instead of cloning from source.json |
 | `--log-level` | `INFO` | Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |
 | `--verbose` | `false` | Show verbose output with file and line numbers |
 
-### Example Usage
+### Understanding Volume Mounts
+
+When using the container, you can mount directories based on your needs:
+
+| Volume Mount | Required? | Purpose | When to Use |
+|--------------|-----------|---------|-------------|
+| `-v ./config:/config:z` | **Required** | Configuration files | Always - contains your `plugins-list.yaml`, `source.json`, patches, and overlays |
+| `-v ./workspace:/workspace:z` | Optional | Source code location | Only if using `--use-local` OR if you want to preserve/inspect the cloned/patched remote repository |
+| `-v ./outputs:/outputs:z` | Optional | Build artifacts | Only if you want the output `.tgz` files saved locally (otherwise they stay in the container) |
+
+**Important**: These volume mount paths (`/config`, `/workspace`, `/outputs`) correspond to the default values of `--config-dir`, `--repo-path`, and `--output-dir`. If you override these arguments with custom paths, adjust your volume mounts accordingly.
+
+**Note**: Use the `:z` flag for systems with SELinux enabled (RHEL/Fedora/CentOS). On other systems, you can omit it.
+
+### Container Usage Examples
 
-#### Build plugins from backstage/community-plugins (todo workspace)
+The following examples demonstrate common use cases with the container image. All examples assume you have the necessary configuration files (`source.json`, `plugins-list.yaml`, and optionally patches/overlays) in your configuration directory. See the [Configuration](#configuration) section for details.
 
-**Local Execution:**
+#### Minimal example (no local files saved)
+
+This minimal example builds the TODO plugins without saving the workspace or output files locally:
 
 ```bash
-python -m rhdh_dynamic_plugin_factory.cli \
-  --config-dir ./config \
-  --repo-path ./workspace \
-  --workspace-path workspaces/todo \
-  --output-dir ./outputs \
-  --no-push-images \
-  --log-level DEBUG
+podman run --rm -it \
+  --device /dev/fuse \
+  -v ./examples/example-config-todo:/config:z \
+  quay.io/rhdh-community/dynamic-plugins-factory:latest \
+  --workspace-path workspaces/todo
 ```
 
-**Container Execution:**
+This will clone the repository, build the plugins, and NOT push the result to a remote repository.
+
+#### Build plugins and save outputs locally
+
+This example builds plugins and saves the `.tgz` files to your local `./outputs/` directory:
 
 ```bash
 podman run --rm -it \
   --device /dev/fuse \
   -v ./config:/config:z \
-  -v ./workspace:/workspace:z \
   -v ./outputs:/outputs:z \
-  -e LOG_LEVEL=DEBUG \
   quay.io/rhdh-community/dynamic-plugins-factory:latest \
-  --workspace-path workspaces/todo \
-  --no-push-images
+  --workspace-path workspaces/todo
 ```
 
-Both methods will:
-
-1. Load configurations from the local `./config` directory
-2. Clone the repository specified in `./config/source.json` to `./workspace`
-3. Apply patches and overlays from `./config/patches/` and `./config/<plugin-path>/overlay/` to `./workspace`
-4. Install dependencies in `./workspace/workspaces/todo`
-5. Export and package plugins listed in `./config/plugins-list.yaml`
-6. Output artifacts to the local `./outputs/` directory
-7. Skip pushing to registry (`--no-push-images`)
+This will clone the repository specified in `./config/source.json`, build the plugins listed in `./config/plugins-list.yaml`, and save the `.tgz` files to `./outputs/`.
 
 #### Build and push to registry
 
-**Local Execution:**
+This example builds plugins and pushes them directly to a container registry (no local `.tgz` files saved).
 
-```bash
-# Set registry credentials in config/.env or environment
-export REGISTRY_URL=quay.io
-export REGISTRY_USERNAME=myuser
-export REGISTRY_PASSWORD=mytoken
-export REGISTRY_NAMESPACE=mynamespace
-
-python -m rhdh_dynamic_plugin_factory.cli \
-  --config-dir ./config \
-  --repo-path ./workspace \
-  --workspace-path workspaces/announcements \
-  --output-dir ./outputs \
-  --push-images
-```
-
-**Container Execution:**
+First, create a `./config/.env` file with your registry credentials:
 
 ```bash
-# Pass registry credentials as environment variables
-podman run --rm -it \
-  --device /dev/fuse \
-  -v ./config:/config:z \
-  -v ./workspace:/workspace:z \
-  -v ./outputs:/outputs:z \
-  -e REGISTRY_URL=quay.io \
-  -e REGISTRY_USERNAME=myuser \
-  -e REGISTRY_PASSWORD=mytoken \
-  -e REGISTRY_NAMESPACE=mynamespace \
-  quay.io/rhdh-community/dynamic-plugins-factory:latest \
-  --workspace-path workspaces/announcements \
-  --push-images
+REGISTRY_URL=quay.io
+REGISTRY_USERNAME=myuser
+REGISTRY_PASSWORD=mytoken
+REGISTRY_NAMESPACE=mynamespace
 ```
 
-**Note:** For security, consider providing registry configurations through the `config/.env` file
+Then run the factory with `--push-images`:
 
 ```bash
-# Using environment file
 podman run --rm -it \
   --device /dev/fuse \
   -v ./config:/config:z \
-  -v ./workspace:/workspace:z \
-  -v ./outputs:/outputs:z \
-  --env-file ./config/.env \
   quay.io/rhdh-community/dynamic-plugins-factory:latest \
-  --repo-path /workspace \
   --workspace-path workspaces/announcements \
-  --output-dir /outputs \
   --push-images
 ```
 
-#### Using a local repository (skip cloning)
-
-If you already have the source code locally, use the `--use-local` flag to skip cloning from `source.json` AND/OR not include `source.json` in the config folder:
-
-**Local Execution:**
+The factory will automatically read the load the environmental variables from `./config/.env`.
 
-```bash
-# Ensure workspace already exists at --repo-path
-# The --use-local flag will skip cloning even if source.json exists
-
-python -m rhdh_dynamic_plugin_factory.cli \
-  --config-dir ./config \
-  --repo-path ./existing-workspace \
-  --workspace-path . \
-  --output-dir ./outputs \
-  --use-local \
-  --no-push-images
-```
+#### Using a local repository (skip cloning)
 
-**Container Execution:**
+If you already have the source code locally, use the `--use-local` flag and mount your existing workspace:
 
 ```bash
-# Mount your existing workspace directory
 podman run --rm -it \
   --device /dev/fuse \
   -v ./config:/config:z \
   -v /path/to/existing-workspace:/workspace:z \
   -v ./outputs:/outputs:z \
   quay.io/rhdh-community/dynamic-plugins-factory:latest \
-  --config-dir /config \
-  --workspace-path . \
-  --use-local \
-  --no-push-images
+  --workspace-path path/to/workspace \
+  --use-local
 ```
 
-**Note:** When using `--use-local`, patches and overlays will still be applied to your local repository. Make sure you have backups or are using version control before running the tool with a local repository.
+**Note:** When using `--use-local`, patches and overlays will still be applied to your local repository. Make sure you have backups or are using version control.
 
 ## Output
 
@@ -401,194 +349,38 @@ NOTE: If the repository name (ex: plugin-name-dynamic) in the namespace specifie
 
 ## Examples
 
-See the `examples` directory for complete configuration examples:
-
-### TODO Workspace Example
+The `examples` directory contains ready-to-use configuration examples demonstrating different use cases and features.
 
-Located at [`examples/example-config-todo`](./examples/example-config-todo/)
+| Example | Description | Details |
+|---------|-------------|---------|
+| **TODO** | Basic workspace with custom scalprum-config | [View README](./examples/example-config-todo/) |
+| **GitLab** | Overlays for non-BCP workspace format | [View README](./examples/example-config-gitlab/) |
+| **AWS ECS** | Patches and embed packages in plugins-list.yaml | [View README](./examples/example-config-aws-ecs/) |
 
-This example contains a custom `scalprum-config.json` file and uses the standard backstage community plugins (BCP) workspace format.
-The process is very similar if you also want to include a custom `backstage.json` or `app-config.dynamic.yaml` file.
+### Quick Example: TODO Workspace
 
-**Local Execution:**
-
-```bash
-python -m rhdh_dynamic_plugin_factory.cli \
-  --config-dir ./examples/example-config-todo \
-  --repo-path ./workspace \
-  --workspace-path workspaces/todo \
-  --output-dir ./outputs \
-  --no-push-images
-```
-
-**Container Execution:**
+Build the TODO plugin from Backstage community plugins:
 
 ```bash
 podman run --rm -it \
   --device /dev/fuse \
   -v ./examples/example-config-todo:/config:z \
-  -v ./workspace:/workspace:z \
-  -v ./outputs:/outputs:z \
   quay.io/rhdh-community/dynamic-plugins-factory:latest \
   --workspace-path workspaces/todo \
   --no-push-images
 ```
 
-#### Package Verification
-
-Afterwards, you can verify that the plugin functions correctly by dynamically installing them into your RHDH instance by adding the newly published plugins into the `dynamic-plugins.yaml` file of your RHDH instance. You may need to add additional `pluginConfig` fields if your plugin requires additional configurations.
-
-```yaml
-includes:
-  - dynamic-plugins.default.yaml
-plugins:
-  - package: oci://quay.io/{REGISTRY_NAMESPACE}/backstage-community-plugin-todo:0.12.0!backstage-community-plugin-todo
-    disabled: false
-    pluginConfig: # `pluginConfig` may be required for additional configurations such as mounting the components
-      dynamicPlugins:
-        frontend:
-          backstage-community.plugin-todo:
-            mountPoints:
-              - mountPoint: entity.page.todo/cards
-                importName: EntityTodoContent
-            entityTabs:
-              - path: /todo
-                title: Todo
-                mountPoint: entity.page.todo
-  - package: oci://quay.io/{REGISTRY_NAMESPACE}/backstage-community-plugin-todo-backend:0.13.0!backstage-community-plugin-todo-backend 
-    disabled: false
-```
-
-We will show an example of how to verify with [RHDH Local](https://github.com/redhat-developer/rhdh-local).
-
-1. If the OCI images were pushed to a previously non-existent repository, please ensure it's now a public repository (or you can setup podman credentials for subsequent steps)
-2. Create a `dynamic-plugins.override.yaml` file with the plugin config above. Replace the `{REGISTRY_NAMESPACE}` with the registry namespace used to publish the plugins.
-3. Import a catalog entity the `todo` plugin with. We will be importing the backstage repository via `config/app-config/app-config.local.yaml`:
-  
-    ```yaml
-    catalog:
-      locations:
-        - type: url
-          target: https://github.com/backstage/backstage/blob/master/catalog-info.yaml
-          rules: 
-            - allow: [Component]
-    ```
-
-4. Start the RHDH instance with `podman compose up -d`
-5. Navigate to <http://localhost:7007/catalog/default/component/backstage/todo> and verify that the `backstage` catalog entity appears, and a `todo` tab appears containing a table of all `TODO` comments in the source code of the catalog entity.
-6. Clean up with `podman compose down --volumes`
-
-### Gitlab Workspace Example
-
-Located at [`examples/example-config-gitlab`](./examples/example-config-gitlab/)
-
-This example contains overlays used to override entire files contained in the gitlab workspace at <https://github.com/immobiliare/backstage-plugin-gitlab> which does not use the standard BCP workspace format. The `--workspace-path` is set to `.` (root of repository).
-
-**Local Execution:**
-
-```bash
-python -m rhdh_dynamic_plugin_factory.cli \
-  --config-dir ./examples/example-config-gitlab \
-  --repo-path ./workspace \
-  --workspace-path . \
-  --output-dir ./outputs \
-```
-
-**Container Execution:**
-
-```bash
-podman run --rm -it \
-  --device /dev/fuse \
-  -v ./examples/example-config-gitlab:/config:z \
-  -v ./workspace:/workspace:z \
-  -v ./outputs:/outputs:z \
-  quay.io/rhdh-community/dynamic-plugins-factory:latest \
-  --workspace-path . \
-```
-
-### AWS ECS Workspace Example
+This example includes:
 
-Located at [`examples/example-config-aws-ecs`](./examples/example-config-aws-ecs/)
+- Custom `scalprum-config.json` configuration
+- Standard Backstage Community Plugins (BCP) workspace format
+- Both frontend and backend plugins in the workspace
 
-This example contains a `patches` folder used for small patches as well as custom export arguments for the `ecs` backend plugin in the [`plugins-list.yaml`](./examples/example-config-aws-ecs/plugins-list.yaml) to embed additional packages during the dynamic plugin export. This workspace also does not use the standard BCP workspace format.
+For detailed instructions, package verification steps, and additional examples, see the individual README files linked in the table above.
 
-**Local Execution:**
+## Local Development & Contributing
 
-```bash
-python -m rhdh_dynamic_plugin_factory.cli \
-  --config-dir ./examples/example-config-aws-ecs \
-  --repo-path ./workspace \
-  --workspace-path . \
-  --output-dir ./outputs \
-```
-
-**Container Execution:**
-
-```bash
-podman run --rm -it \
-  --device /dev/fuse \
-  -v ./examples/example-config-aws-ecs:/config:z \
-  -v ./workspace:/workspace:z \
-  -v ./outputs:/outputs:z \
-  quay.io/rhdh-community/dynamic-plugins-factory:latest \
-  --repo-path /workspace \
-```
-
-## Development
-
-### Project Structure
-
-```bash
-rhdh-dynamic-plugin-factory/
-├── src/rhdh_dynamic_plugin_factory/
-|   ├── __init__.py         
-│   ├── __main__.py              # Package entry point
-│   ├── cli.py                   # CLI implementation
-│   ├── config.py                # Configuration classes
-│   ├── logger.py                # Logging setup
-|   └── utils.py                 # Utility functions
-├── scripts/
-│   ├── export-workspace.sh      # Plugin export script
-│   └── override-sources.sh      # Patch/overlay script
-├── tests/                       # Unit Tests
-├── examples/                    # Example configuration sets
-├── default.env                  # Default environment settings
-├── requirements.txt             # Python dependencies
-└── requirements.dev.txt         # Development dependencies
-```
-
-### Running Tests
-
-#### Run all tests
-
-```bash
-pytest tests/
-```
-
-#### Run tests with verbose output
-
-```bash
-pytest tests/ -v
-```
-
-#### Run tests for a specific module
-
-```bash
-pytest tests/test_config.py -v
-```
-
-#### Run a specific test class or method
-
-```bash
-pytest tests/test_config.py::TestPluginFactoryConfigLoadFromEnv -v
-pytest tests/test_config.py::TestPluginFactoryConfigLoadFromEnv::test_load_from_env_valid_configuration -v
-```
-
-#### Run with coverage reporting
-
-```bash
-pytest tests/ --cov=src/rhdh_dynamic_plugin_factory --cov-report=term-missing
-```
+For users who want to run the factory locally without containers or contribute to the project, see [CONTRIBUTING.md](./CONTRIBUTING.md).
 
 ## Resources
 
diff --git a/examples/example-config-aws-ecs/README.md b/examples/example-config-aws-ecs/README.md
new file mode 100644
index 0000000..1eff03b
--- /dev/null
+++ b/examples/example-config-aws-ecs/README.md
@@ -0,0 +1,170 @@
+# AWS ECS Example Configuration
+
+This example demonstrates building AWS ECS plugins with patches for code fixes and embedded packages for additional dependencies.
+
+## Table of Contents
+
+- [AWS ECS Example Configuration](#aws-ecs-example-configuration)
+  - [Table of Contents](#table-of-contents)
+  - [Overview](#overview)
+  - [Example Config Directory Structure](#example-config-directory-structure)
+    - [Configuration Files](#configuration-files)
+  - [Understanding Patches](#understanding-patches)
+    - [Patch Format](#patch-format)
+    - [How Patches Work](#how-patches-work)
+    - [Creating Patches](#creating-patches)
+  - [Embed Packages](#embed-packages)
+  - [Quick Start](#quick-start)
+    - [Container Execution (Recommended)](#container-execution-recommended)
+    - [Local Development](#local-development)
+  - [Expected Output](#expected-output)
+  - [Publishing the package](#publishing-the-package)
+  - [Next Steps](#next-steps)
+
+## Overview
+
+This example builds the frontend and backend ECS plugins from the [awslabs/backstage-plugins-for-aws](https://github.com/awslabs/backstage-plugins-for-aws) repository. It includes the following configurations:
+
+1. **Patches**: Small, targeted code changes applied via diff files
+2. **Embed Packages**: Including additional dependency packages in the dynamic plugin export
+
+## Example Config Directory Structure
+
+```bash
+example-config-aws-ecs/
+├── backstage.json                    # Backstage configuration
+├── patches/
+│   └── 1-avoid-double-wildcards.patch  #  Path File
+├── plugins-list.yaml                 # Plugins with embed-package arguments
+└── source.json                       # Source repository configuration
+```
+
+### Configuration Files
+
+- **`source.json`**: Specifies the AWS plugins repository and git reference to clone from
+- **`plugins-list.yaml`**: Lists plugins with `--embed-package` arguments for shared dependencies
+- **`backstage.json`**: Backstage configuration file
+- **`patches/`**: Contains patch files
+
+## Understanding Patches
+
+Patches are **diff files** that apply small, targeted changes to the source code. Unlike overlays (which replace/adds entire files), patches modify specific lines.
+
+### Patch Format
+
+Patches use the standard unified diff format:
+
+```diff
+--- a/path/to/file
++++ b/path/to/file
+@@ -line,count +line,count @@
+ context line
+-removed line
++added line
+ context line
+```
+
+### How Patches Work
+
+1. The factory clones the source repository
+2. Before building, it applies all `.patch` files from `config/patches/` in alphabetical order
+3. Each patch modifies specific lines in the source files
+4. The patched source is then built and exported
+
+**Warning**: Patches are destructive - they permanently modify files in the workspace directory. Please make sure to have source control if using a local repository.
+
+### Creating Patches
+
+To create your own patch:
+
+1. Make changes to files in your workspace
+2. Generate a patch file:
+
+   ```bash
+   git diff > my-fix.patch
+   ```
+
+3. Place the patch in `config/patches/`
+4. Prefix with a number for ordering (e.g., `01-my-fix.patch`)
+
+## Embed Packages
+
+The `--embed-package` argument bundles shared dependencies directly into the dynamic plugin.
+
+In this example, the ECS backend plugin embeds common AWS packages so that the backend application functions correctly.
+
+```yaml
+plugins/ecs/backend: --embed-package @aws/aws-core-plugin-for-backstage-common --embed-package @aws/aws-core-plugin-for-backstage-node
+```
+
+## Quick Start
+
+### Container Execution (Recommended)
+
+From the repository root, run:
+
+```bash
+podman run --rm -it \
+  --device /dev/fuse \
+  -v ./examples/example-config-aws-ecs:/config:z \
+  -v ./outputs:/outputs:z \
+  quay.io/rhdh-community/dynamic-plugins-factory:latest \
+  --workspace-path .
+```
+
+Note: `--workspace-path .` is used because this repository does not follow the backstage community plugins (BCP) repository structure where there are multiple yarn workspaces. Instead the plugins are stored in the main workspace, so root of the workspace is also the root of the repository in this example.
+
+### Local Development
+
+From the repository root, run:
+
+```bash
+python -m src.rhdh_dynamic_plugin_factory \
+  --config-dir ./examples/example-config-aws-ecs \
+  --workspace-path . \
+  --repo-path ./workspace \
+  --output-dir ./outputs
+```
+
+This will do the following:
+
+1. The factory clones the AWS plugins repository to `./workspace`
+2. The `1-avoid-double-wildcards.patch` is applied to fix workspace configuration
+3. Dependencies are installed at the repository root
+4. Frontend and backend ECS plugins are compiled
+5. Shared AWS packages are embedded in the backend plugin
+6. Plugins are exported as dynamic plugins using the RHDH CLI
+7. Plugin tarballs and integrity files are created in `./outputs`
+
+## Expected Output
+
+After successful execution, you'll find these files in `./outputs/`:
+
+```bash
+outputs/
+├── aws-ecs-plugin-for-backstage-0.2.0.tgz
+├── aws-ecs-plugin-for-backstage-0.2.0.tgz.integrity
+├── aws-ecs-plugin-for-backstage-backend-0.3.0.tgz
+└── aws-ecs-plugin-for-backstage-backend-0.3.0.tgz.integrity
+```
+
+Note: Version numbers may vary depending on the plugin versions in the source repository.
+
+## Publishing the package
+
+If you want to publish the package, you will need to add a `--push-image` argument and provide the following environmental variables in the `/config/.env` file:
+
+```bash
+REGISTRY_URL="quay.io"
+REGISTRY_USERNAME="your-username"
+REGISTRY_PASSWORD="your-password" 
+REGISTRY_NAMESPACE="your-namespace"
+REGISTRY_INSECURE="false"
+```
+
+## Next Steps
+
+- Try the [GitLab example](../example-config-gitlab/) to learn about overlays
+- Review the [TODO example](../example-config-todo/) for a simpler use case
+- Read the [main README](../../README.md) for more configuration options
+- Explore other AWS plugins in the repository
diff --git a/examples/example-config-gitlab/README.md b/examples/example-config-gitlab/README.md
new file mode 100644
index 0000000..4783cf0
--- /dev/null
+++ b/examples/example-config-gitlab/README.md
@@ -0,0 +1,128 @@
+# GitLab Example Configuration
+
+This example demonstrates building GitLab plugins from a non-standard repository structure using overlays to modify source files.
+
+## Table of Contents
+
+- [GitLab Example Configuration](#gitlab-example-configuration)
+  - [Table of Contents](#table-of-contents)
+  - [Overview](#overview)
+  - [Example Config Directory Structure](#example-config-directory-structure)
+    - [Configuration Files](#configuration-files)
+  - [Understanding Overlays](#understanding-overlays)
+    - [How Overlays Work](#how-overlays-work)
+  - [Quick Start](#quick-start)
+    - [Container Execution (Recommended)](#container-execution-recommended)
+    - [Local Development](#local-development)
+  - [Expected Output](#expected-output)
+  - [Publishing the package](#publishing-the-package)
+  - [Next Steps](#next-steps)
+
+## Overview
+
+This example builds the frontend and backend GitLab plugins from the [immobiliare/backstage-plugin-gitlab](https://github.com/immobiliare/backstage-plugin-gitlab) repository. It uses overlays to replace specific source files with custom versions needed for proper dynamic plugin export.
+
+## Example Config Directory Structure
+
+```bash
+example-config-gitlab/
+├── packages/
+│   └── gitlab-backend/
+│       └── overlay/
+│           └── src/
+│               ├── bundle.ts         # Custom bundle configuration
+│               └── index.ts          # Custom plugin export
+├── plugins-list.yaml                 # List of plugins to build
+└── source.json                       # Source repository configuration
+```
+
+### Configuration Files
+
+- **`source.json`**: Specifies the GitLab plugin repository and git eference to clone from
+- **`plugins-list.yaml`**: List of path to the GitLab frontend and backend packages to build
+- **`packages/gitlab-backend/overlay/`**: Contains replacement source files
+
+## Understanding Overlays
+
+Overlays allow you to replace/add entire files in the plugin source code before building.
+
+The overlay directory structure mirrors the plugin's source structure. Files in the overlay are copied over the original files at build time.
+
+### How Overlays Work
+
+1. The factory clones the source repository
+2. Before building, it copies files from `config/<plugin-path>/overlay/` to the corresponding paths in `workspace/<plugin-path>/`
+3. The overlaid files replace the original files completely if one exists, otherwise it will add the file
+4. The modified source is then built and exported
+
+**Warning**: Overlays are destructive - they permanently modify files in the workspace directory. Please make sure to have source control if using a local repository.
+
+## Quick Start
+
+### Container Execution (Recommended)
+
+From the repository root, run:
+
+```bash
+podman run --rm -it \
+  --device /dev/fuse \
+  -v ./examples/example-config-gitlab:/config:z \
+  -v ./outputs:/outputs:z \
+  -f ./workspace:/workspace:z \
+  quay.io/rhdh-community/dynamic-plugins-factory:latest \
+  --workspace-path .
+```
+
+Note: `--workspace-path .` is used because this repository does not follow the backstage community plugins (BCP) repository structure where there are multiple yarn workspaces. Instead the plugins are stored in the main workspace, so root of the workspace is also the root of the repository in this example.
+
+### Local Development
+
+From the repository root, run:
+
+```bash
+python -m src.rhdh_dynamic_plugin_factory \
+  --config-dir ./examples/example-config-gitlab \
+  --workspace-path . \
+  --output-dir ./outputs
+```
+
+This will do the following:
+
+1. The factory clones the GitLab plugin repository to `./workspace`
+2. Custom `bundle.ts` and `index.ts` files are copied to `./workspace/packages/gitlab-backend/src/`
+3. Dependencies are installed at the repository root
+4. Both frontend and backend plugins are compiled
+5. Plugins are exported as dynamic plugins using the RHDH CLI
+6. Plugin tarballs and integrity files are created in `./outputs`
+
+## Expected Output
+
+After successful execution, you'll find these files in `./outputs/`:
+
+```bash
+outputs/
+├── backstage-plugin-gitlab-6.13.0.tgz
+├── backstage-plugin-gitlab-6.13.0.tgz.integrity
+├── backstage-plugin-gitlab-backend-6.13.0.tgz
+└── backstage-plugin-gitlab-backend-6.13.0.tgz.integrity
+```
+
+Note: Version numbers correspond to the tag specified in `source.json`.
+
+## Publishing the package
+
+If you want to publish the package, you will need to add a `--push-image` argument and provide the following environmental variables in the `/config/.env` file:
+
+```bash
+REGISTRY_URL="quay.io"
+REGISTRY_USERNAME="your-username"
+REGISTRY_PASSWORD="your-password" 
+REGISTRY_NAMESPACE="your-namespace"
+REGISTRY_INSECURE="false"
+```
+
+## Next Steps
+
+- Try the [AWS ECS example](../example-config-aws-ecs/) to learn about patches
+- Review the [TODO example](../example-config-todo/) for a simpler use case
+- Read the [main README](../../README.md) for more configuration options
diff --git a/examples/example-config-todo/README.md b/examples/example-config-todo/README.md
new file mode 100644
index 0000000..65061ec
--- /dev/null
+++ b/examples/example-config-todo/README.md
@@ -0,0 +1,186 @@
+# TODO Example Configuration
+
+This example demonstrates building the TODO plugin from the Backstage Community Plugins repository with a custom `scalprum-config.json` configuration.
+
+## Table of Contents
+
+- [TODO Example Configuration](#todo-example-configuration)
+  - [Table of Contents](#table-of-contents)
+  - [Overview](#overview)
+  - [Example Config Directory Structure](#example-config-directory-structure)
+    - [Configuration Files](#configuration-files)
+  - [Quick Start](#quick-start)
+    - [Container Execution (Recommended)](#container-execution-recommended)
+    - [Local Development](#local-development)
+  - [Expected Output](#expected-output)
+  - [Publishing the package](#publishing-the-package)
+  - [Package Verification](#package-verification)
+    - [Testing with RHDH Local](#testing-with-rhdh-local)
+      - [Prerequisites](#prerequisites)
+      - [Step 1: Configure Dynamic Plugins](#step-1-configure-dynamic-plugins)
+      - [Step 2: Import a Catalog Entity](#step-2-import-a-catalog-entity)
+      - [Step 3: Start RHDH Local](#step-3-start-rhdh-local)
+      - [Step 4: Verify the Plugin](#step-4-verify-the-plugin)
+      - [Step 5: Clean Up](#step-5-clean-up)
+  - [Next Steps](#next-steps)
+
+## Overview
+
+This example builds both the frontend and backend TODO plugins from the Backstage Community Plugins repository. It includes a custom Scalprum configuration file to control the dynamic plugin export behavior.
+
+## Example Config Directory Structure
+
+```bash
+example-config-todo/
+├── plugins/
+│   └── todo/
+│       └── scalprum-config.json    # Custom Scalprum configuration to overlay
+├── plugins-list.yaml                # List of plugins to build
+└── source.json                      # Source repository configuration
+```
+
+### Configuration Files
+
+- **`source.json`**: Specifies the Backstage Community Plugins repository and git reference to clone from
+- **`plugins-list.yaml`**: Lists the path to the TODO frontend and backend plugins to build with respect to the workspace path
+- **`plugins/todo/scalprum-config.json`**: Custom Scalprum configuration that will be overlaid on top of the plugin source directory
+
+## Quick Start
+
+### Container Execution (Recommended)
+
+From the repository root, run:
+
+```bash
+podman run --rm -it \
+  --device /dev/fuse \
+  -v ./examples/example-config-todo:/config:z \
+  -v ./outputs:/outputs:z \
+  quay.io/rhdh-community/dynamic-plugins-factory:latest \
+  --workspace-path workspaces/todo
+```
+
+### Local Development
+
+From the repository root, run:
+
+```bash
+python -m src.rhdh_dynamic_plugin_factory \
+  --config-dir ./examples/example-config-todo \
+  --repo-path ./workspace \
+  --workspace-path workspaces/todo \
+  --output-dir ./outputs
+```
+
+This will do the following:
+
+1. The factory clones the Backstage Community Plugins repository to `./workspace`
+2. The custom `scalprum-config.json` is overlaid on top of the plugin source directory
+3. Dependencies are installed in the TODO workspace
+4. Both frontend and backend plugins are exported and packaged using the RHDH CLI with the arguments defined in `./config/plugins-list.yaml` which in this case is no additional arguments
+5. Plugin tarballs and integrity files are created in `./outputs`
+
+## Expected Output
+
+After successful execution, you'll find these files in `./outputs/`:
+
+```bash
+outputs/
+├── backstage-community-plugin-todo-0.12.0.tgz
+├── backstage-community-plugin-todo-0.12.0.tgz.integrity
+├── backstage-community-plugin-todo-backend-0.13.0.tgz
+└── backstage-community-plugin-todo-backend-0.13.0.tgz.integrity
+```
+
+Note: Version numbers may vary depending on the plugin versions in the source repository.
+
+## Publishing the package
+
+If you want to publish the package, you will need to add a `--push-image` argument and provide the following environmental variables in the `/config/.env` file:
+
+```bash
+REGISTRY_URL="quay.io"
+REGISTRY_USERNAME="your-username"
+REGISTRY_PASSWORD="your-password" 
+REGISTRY_NAMESPACE="your-namespace"
+REGISTRY_INSECURE="false"
+```
+
+## Package Verification
+
+### Testing with RHDH Local
+
+You can verify the plugins work correctly by installing them in an RHDH instance. Here's how to test with [RHDH Local](https://github.com/redhat-developer/rhdh-local):
+
+#### Prerequisites
+
+- [RHDH Local](https://github.com/redhat-developer/rhdh-local) repository cloned
+- [Podman](https://podman.io/) installed
+- Plugins built and published to a container registry
+
+#### Step 1: Configure Dynamic Plugins
+
+Create a `dynamic-plugins.override.yaml` file in the RHDH Local config directory:
+
+```yaml
+includes:
+  - dynamic-plugins.default.yaml
+plugins:
+  - package: oci://quay.io/{REGISTRY_NAMESPACE}/backstage-community-plugin-todo:0.12.0!backstage-community-plugin-todo
+    disabled: false
+    pluginConfig:
+      dynamicPlugins:
+        frontend:
+          backstage-community.plugin-todo:
+            mountPoints:
+              - mountPoint: entity.page.todo/cards
+                importName: EntityTodoContent
+            entityTabs:
+              - path: /todo
+                title: Todo
+                mountPoint: entity.page.todo
+  - package: oci://quay.io/{REGISTRY_NAMESPACE}/backstage-community-plugin-todo-backend:0.13.0!backstage-community-plugin-todo-backend 
+    disabled: false
+```
+
+Replace `{REGISTRY_NAMESPACE}` with your registry namespace.
+
+**Note**: If you pushed to a private repository, make it public or configure Podman credentials.
+
+#### Step 2: Import a Catalog Entity
+
+Create or edit `config/app-config/app-config.local.yaml` to import the Backstage repository:
+
+```yaml
+catalog:
+  locations:
+    - type: url
+      target: https://github.com/backstage/backstage/blob/master/catalog-info.yaml
+      rules: 
+        - allow: [Component]
+```
+
+#### Step 3: Start RHDH Local
+
+```bash
+podman compose up -d
+```
+
+#### Step 4: Verify the Plugin
+
+1. Open your browser to <http://localhost:7007>
+2. Navigate to the Backstage component located at <http://localhost:7007/catalog/default/component/backstage>
+3. Click on the **Todo** tab
+4. You should see a table containing all `TODO` comments from the Backstage source code
+
+#### Step 5: Clean Up
+
+```bash
+podman compose down --volumes
+```
+
+## Next Steps
+
+- Try the [GitLab example](../example-config-gitlab/) to learn about overlays
+- Try the [AWS ECS example](../example-config-aws-ecs/) to learn about patches and embed packages
+- Read the [main README](../../README.md) for more configuration options

From 758d23a8dbd8263e14b63286ee41c364f87e8447 Mon Sep 17 00:00:00 2001
From: Frank Kong <frkong@redhat.com>
Date: Fri, 7 Nov 2025 14:44:19 -0500
Subject: [PATCH 2/2] chore: remove the examples and documentation from the
 final build image

Signed-off-by: Frank Kong <frkong@redhat.com>
---
 .dockerignore | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.dockerignore b/.dockerignore
index 8be10a4..72be04a 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -2,6 +2,7 @@
 config/
 outputs/
 workspace/
+examples/
 
 # IDE 
 .vscode/