example-config-toolbox

Toolbox Example Configuration

This example demonstrates building the Toolbox plugins from a third-party repository with patches and a backend module.

Table of Contents

• Toolbox Example Configuration
  • Table of Contents
  • Overview
  • Example Config Directory Structure
    • Configuration Files
  • Understanding the Patch
    • How Patches Work
  • Quick Start
    • Container Execution (Recommended)
    • Local Development
  • Expected Output
  • Publishing the package
  • Next Steps

Overview

This example builds frontend, backend, and backend module plugins from the drodil/backstage-plugin-toolbox repository. It includes the following configurations:

1. Patches: A patch to fix workspace configuration that prevents packaging generated export artifacts since the frontend plugin in this example also contains an alpha package with support for the new frontend system.
2. Backend Module: Demonstrates building a backend module plugin (toolbox-backend-module-whois) in addition to the main frontend and backend plugins

Example Config Directory Structure

example-config-toolbox/
├── patches/
│   └── 1-avoid-double-wildcards.patch  # Patch file
├── plugins-list.yaml                   # List of plugins to build
└── source.json                         # Source repository configuration

Configuration Files

• source.json: Specifies the Toolbox plugin repository and git reference to clone from. The repo-ref field is optional; when omitted, the repository's default branch is used. The workspace-path field can also be set here instead of using --workspace-path.
• plugins-list.yaml: Lists the path to the Toolbox frontend, backend, and backend module plugins to build
• patches/: Contains patch files applied before building

Understanding the Patch

The 1-avoid-double-wildcards.patch modifies the workspace packages glob in package.json from plugins/** to plugins/*. This prevents Yarn from treating the dist-dynamic directories (generated by the RHDH CLI export command) as additional workspaces, which would cause build failures.

--- a/package.json
+++ b/package.json
@@ -30,7 +30,7 @@
   },
   "workspaces": {
     "packages": [
-      "plugins/**"
+      "plugins/*"
     ]
   },

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.

Quick Start

Container Execution (Recommended)

From the repository root, run:

podman run --rm -it \
  --device /dev/fuse \
  -v ./examples/example-config-toolbox:/config:z \
  -v ./outputs:/outputs:z \
  quay.io/rhdh-community/dynamic-plugins-factory:latest \

Note: workspace-path is set to . in source.json 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:

python -m src.rhdh_dynamic_plugin_factory \
  --config-dir ./examples/example-config-toolbox \
  --repo-path ./source \
  --output-dir ./outputs

Or using CLI args instead of source.json:

python -m src.rhdh_dynamic_plugin_factory \
  --source-repo https://github.com/drodil/backstage-plugin-toolbox \
  --source-ref 32ff2046741478f0964cf63a97fae5cc2f1a93d8 \
  --config-dir ./examples/example-config-toolbox \
  --workspace-path . \
  --repo-path ./source \
  --output-dir ./outputs

This will do the following:

1. The factory clones the Toolbox plugin repository to ./source
2. The 1-avoid-double-wildcards.patch is applied to fix workspace configuration
3. Dependencies are installed at the repository root
4. Frontend, backend, and backend module 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:

outputs/
├── backstage-plugin-toolbox-X.Y.Z.tgz
├── backstage-plugin-toolbox-X.Y.Z.tgz.integrity
├── backstage-plugin-toolbox-backend-X.Y.Z.tgz
├── backstage-plugin-toolbox-backend-X.Y.Z.tgz.integrity
├── backstage-plugin-toolbox-backend-module-whois-X.Y.Z.tgz
└── backstage-plugin-toolbox-backend-module-whois-X.Y.Z.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:

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 to learn about embed packages
• Try the GitLab example to learn about overlays
• Review the TODO example for a simpler use case
• Read the main README for more configuration options