|
| 1 | +# Toolbox Example Configuration |
| 2 | + |
| 3 | +This example demonstrates building the Toolbox plugins from a third-party repository with patches and a backend module. |
| 4 | + |
| 5 | +## Table of Contents |
| 6 | + |
| 7 | +- [Toolbox Example Configuration](#toolbox-example-configuration) |
| 8 | + - [Table of Contents](#table-of-contents) |
| 9 | + - [Overview](#overview) |
| 10 | + - [Example Config Directory Structure](#example-config-directory-structure) |
| 11 | + - [Configuration Files](#configuration-files) |
| 12 | + - [Understanding the Patch](#understanding-the-patch) |
| 13 | + - [How Patches Work](#how-patches-work) |
| 14 | + - [Quick Start](#quick-start) |
| 15 | + - [Container Execution (Recommended)](#container-execution-recommended) |
| 16 | + - [Local Development](#local-development) |
| 17 | + - [Expected Output](#expected-output) |
| 18 | + - [Publishing the package](#publishing-the-package) |
| 19 | + - [Next Steps](#next-steps) |
| 20 | + |
| 21 | +## Overview |
| 22 | + |
| 23 | +This example builds frontend, backend, and backend module plugins from the [drodil/backstage-plugin-toolbox](https://github.com/drodil/backstage-plugin-toolbox) repository. It includes the following configurations: |
| 24 | + |
| 25 | +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. |
| 26 | +2. **Backend Module**: Demonstrates building a backend module plugin (`toolbox-backend-module-whois`) in addition to the main frontend and backend plugins |
| 27 | + |
| 28 | +## Example Config Directory Structure |
| 29 | + |
| 30 | +```bash |
| 31 | +example-config-toolbox/ |
| 32 | +├── patches/ |
| 33 | +│ └── 1-avoid-double-wildcards.patch # Patch file |
| 34 | +├── plugins-list.yaml # List of plugins to build |
| 35 | +└── source.json # Source repository configuration |
| 36 | +``` |
| 37 | + |
| 38 | +### Configuration Files |
| 39 | + |
| 40 | +- **`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`. |
| 41 | +- **`plugins-list.yaml`**: Lists the path to the Toolbox frontend, backend, and backend module plugins to build |
| 42 | +- **`patches/`**: Contains patch files applied before building |
| 43 | + |
| 44 | +## Understanding the Patch |
| 45 | + |
| 46 | +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. |
| 47 | + |
| 48 | +```diff |
| 49 | +--- a/package.json |
| 50 | ++++ b/package.json |
| 51 | +@@ -30,7 +30,7 @@ |
| 52 | + }, |
| 53 | + "workspaces": { |
| 54 | + "packages": [ |
| 55 | +- "plugins/**" |
| 56 | ++ "plugins/*" |
| 57 | + ] |
| 58 | + }, |
| 59 | +``` |
| 60 | + |
| 61 | +### How Patches Work |
| 62 | + |
| 63 | +1. The factory clones the source repository |
| 64 | +2. Before building, it applies all `.patch` files from `config/patches/` in alphabetical order |
| 65 | +3. Each patch modifies specific lines in the source files |
| 66 | +4. The patched source is then built and exported |
| 67 | + |
| 68 | +**Warning**: Patches are destructive - they permanently modify files in the workspace directory. Please make sure to have source control if using a local repository. |
| 69 | + |
| 70 | +## Quick Start |
| 71 | + |
| 72 | +### Container Execution (Recommended) |
| 73 | + |
| 74 | +From the repository root, run: |
| 75 | + |
| 76 | +```bash |
| 77 | +podman run --rm -it \ |
| 78 | + --device /dev/fuse \ |
| 79 | + -v ./examples/example-config-toolbox:/config:z \ |
| 80 | + -v ./outputs:/outputs:z \ |
| 81 | + quay.io/rhdh-community/dynamic-plugins-factory:latest \ |
| 82 | +``` |
| 83 | + |
| 84 | +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. |
| 85 | + |
| 86 | +### Local Development |
| 87 | + |
| 88 | +From the repository root, run: |
| 89 | + |
| 90 | +```bash |
| 91 | +python -m src.rhdh_dynamic_plugin_factory \ |
| 92 | + --config-dir ./examples/example-config-toolbox \ |
| 93 | + --repo-path ./source \ |
| 94 | + --output-dir ./outputs |
| 95 | +``` |
| 96 | + |
| 97 | +Or using CLI args instead of `source.json`: |
| 98 | + |
| 99 | +```bash |
| 100 | +python -m src.rhdh_dynamic_plugin_factory \ |
| 101 | + --source-repo https://github.com/drodil/backstage-plugin-toolbox \ |
| 102 | + --source-ref 32ff2046741478f0964cf63a97fae5cc2f1a93d8 \ |
| 103 | + --config-dir ./examples/example-config-toolbox \ |
| 104 | + --workspace-path . \ |
| 105 | + --repo-path ./source \ |
| 106 | + --output-dir ./outputs |
| 107 | +``` |
| 108 | + |
| 109 | +This will do the following: |
| 110 | + |
| 111 | +1. The factory clones the Toolbox plugin repository to `./source` |
| 112 | +2. The `1-avoid-double-wildcards.patch` is applied to fix workspace configuration |
| 113 | +3. Dependencies are installed at the repository root |
| 114 | +4. Frontend, backend, and backend module plugins are compiled |
| 115 | +5. Plugins are exported as dynamic plugins using the RHDH CLI |
| 116 | +6. Plugin tarballs and integrity files are created in `./outputs` |
| 117 | + |
| 118 | +## Expected Output |
| 119 | + |
| 120 | +After successful execution, you'll find these files in `./outputs`: |
| 121 | + |
| 122 | +```bash |
| 123 | +outputs/ |
| 124 | +├── backstage-plugin-toolbox-X.Y.Z.tgz |
| 125 | +├── backstage-plugin-toolbox-X.Y.Z.tgz.integrity |
| 126 | +├── backstage-plugin-toolbox-backend-X.Y.Z.tgz |
| 127 | +├── backstage-plugin-toolbox-backend-X.Y.Z.tgz.integrity |
| 128 | +├── backstage-plugin-toolbox-backend-module-whois-X.Y.Z.tgz |
| 129 | +└── backstage-plugin-toolbox-backend-module-whois-X.Y.Z.tgz.integrity |
| 130 | +``` |
| 131 | + |
| 132 | +Note: Version numbers may vary depending on the plugin versions in the source repository. |
| 133 | + |
| 134 | +## Publishing the package |
| 135 | + |
| 136 | +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: |
| 137 | + |
| 138 | +```bash |
| 139 | +REGISTRY_URL="quay.io" |
| 140 | +REGISTRY_USERNAME="your-username" |
| 141 | +REGISTRY_PASSWORD="your-password" |
| 142 | +REGISTRY_NAMESPACE="your-namespace" |
| 143 | +REGISTRY_INSECURE="false" |
| 144 | +``` |
| 145 | + |
| 146 | +## Next Steps |
| 147 | + |
| 148 | +- Try the [AWS ECS example](../example-config-aws-ecs/) to learn about embed packages |
| 149 | +- Try the [GitLab example](../example-config-gitlab/) to learn about overlays |
| 150 | +- Review the [TODO example](../example-config-todo/) for a simpler use case |
| 151 | +- Read the [main README](../../README.md) for more configuration options |
0 commit comments