Skip to content

onboard-modular-architecture.md

Latest commit

 

History

History
114 lines (76 loc) · 3.2 KB

onboard-modular-architecture.md

File metadata and controls

114 lines (76 loc) · 3.2 KB

Onboarding a New Modular Architecture Module

This guide outlines the steps to create and onboard a new modular architecture module into the ODH Dashboard.

Prerequisites

  • Node.js and npm installed.
  • Access to the ODH Dashboard repository.

Steps

1. Navigate to the Packages Directory

Open your terminal and navigate to the packages folder within the repository:

cd packages

2. Initialize the Module

Start a new modular architecture project using the installer. Replace <your-module-name> with the desired name for your module.

npx mod-arch-installer -n <your-module-name>

3. Configure the Port

Each module needs a unique local dev port so that multiple federated modules can run simultaneously. To see which ports are already in use, run the validation script:

npm run validate:ports

This prints a complete list of all current port assignments, sourced directly from the workspace package.json files and federation-configmap.yaml.

Convention: Frontend federation ports use the 9100–9399 range. BFF ports use the 4000–4099 range. Pick the next available number in the appropriate range.

Pick an unused port and update both Makefile and package.json:

  1. Update Makefile: Open packages/<your-module-name>/Makefile and find the dev-frontend-federated target. Update the PORT variable:

    dev-frontend-federated:
    cd frontend && AUTH_METHOD=user_token DEPLOYMENT_MODE=federated STYLE_THEME=patternfly PORT=<your-port> npm run start:dev

  2. Update package.json: Open packages/<your-module-name>/package.json and update the module-federation configuration:

    "module-federation": {
  "local": {
    "port": <your-port>
  }
}

  3. Validate uniqueness: Run the port validation script to confirm there are no conflicts:

    node scripts/validate-module-ports.js

    This check also runs automatically in CI and the pre-commit hook.

4. Add Feature Flag

To enable your module in the main dashboard, you need to add a feature flag.

  1. Open frontend/src/concepts/areas/const.ts in the root of the repository.

  2. Search for existing flags (e.g., search for disable or techPreviewFlags).

  3. Add your new feature flag to the appropriate group (e.g., techPreviewFlags):

    export const techPreviewFlags = {
  // ... existing flags
  // yourModuleName: true, // Set to true to enable by default in tech preview, or false otherwise
} satisfies Partial<DashboardCommonConfig>;

5. Run the Application

Now that your project is configured, you can run the entire stack (backend, frontend, and your new module).

From the root of the repository, run:

npm run dev:frontend

And in other terminal

npm run dev:backend

And once you have that in another terminal run

cd packages/<your-module>
make dev-start-federated

This command will start:

  • The Dashboard Backend
  • The Dashboard Frontend (Shell)
  • Your new Modular Architecture Module (Federated)

Access the dashboard in your browser (usually at http://localhost:4000 or the port configured for the shell) and verify that your module is loaded.