diff --git a/README.md b/README.md index dcf726b7..57dfa3ab 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,7 @@ ![Unit tests](https://github.com/DIRACGrid/diracx-web/actions/workflows/diracx-web-components-test.yml/badge.svg?branch=main) ![Integration tests](https://github.com/DIRACGrid/diracx-web/actions/workflows/diracx-web-test.yml/badge.svg?branch=main) ![Deployment](https://github.com/DIRACGrid/diracx-web/actions/workflows/deployment.yml/badge.svg?branch=main) +![Gubbins](https://github.com/DIRACGrid/diracx-web/actions/workflows/gubbins-test.yml/badge.svg?branch=main) **DiracX-Web** is a web application that provides a user-friendly interface to interact with the [DiracX](https://github.com/DIRACGrid/diracx) services. It is part of the [DIRAC](https://github.com/DIRACGrid) ecosystem. @@ -14,9 +15,9 @@ ## Get Started -- **New user?** Learn how to use the application effectively in the [:book: User Guide](docs/user/index.md) -- **Developing a DiracX-Web extension?** Go straight to the [:page_facing_up: Extension README](packages/extensions/README.md) -- **Managing the repository?** Discover tips and tricks in the [:book: Ops Guide](docs/ops/index.md) +- **New user?** Learn how to use the application effectively in the [:book: User Guide](https://diracx.diracgrid.org/en/latest/user/web/) +- **Developing a DiracX-Web extension?** Go straight to the [:page_facing_up: Extension README](https://diracx.diracgrid.org/en/latest/developer/manage_extension/) +- **Managing the repository?** Discover tips and tricks in the [:book: Ops Guide](https://diracx.diracgrid.org/en/latest/dev/setup_environment/) - **Interested in contributing?** Read the [:star: Contributing Document](CONTRIBUTING.md) diff --git a/docs/admin/manage_release.md b/docs/admin/explanations/manage_web_release.md similarity index 100% rename from docs/admin/manage_release.md rename to docs/admin/explanations/manage_web_release.md diff --git a/docs/admin/deploy_instance.md b/docs/admin/how-to/deploy_web_instance.md similarity index 74% rename from docs/admin/deploy_instance.md rename to docs/admin/how-to/deploy_web_instance.md index a6334f6d..a63e29d5 100644 --- a/docs/admin/deploy_instance.md +++ b/docs/admin/how-to/deploy_web_instance.md @@ -3,7 +3,7 @@ ### Development mode -Refer to the [Developer Guide: Setting up you Development Environment](../developer/setup_environment.md) for instructions on running `diracx-web` in development mode. +Refer to the [Developer Guide: Setting up your Development Environment](../../dev/how-to/setup_web_environment.md) for instructions on running `diracx-web` in development mode. ### Production mode @@ -14,7 +14,8 @@ global.images.web.tag: global.images.web.repository: ``` -:bulb: Make sure to update these values to point to the appropriate Docker image and version for your deployment. +!!! tip + Make sure to update these values to point to the appropriate Docker image and version for your deployment. ### Integrating new features/hotfixes @@ -25,14 +26,15 @@ diracxWeb.repoURL: diracxWeb.branch: ``` -:bulb: Make sure to update these values to point to the appropriate Docker image and version for your deployment. +!!! tip + Make sure to update these values to point to the appropriate Docker image and version for your deployment. ## Extension ### `gubbins` extension in development mode -For managing the `gubbins` extension in development mode, refer to the [Developer Guide: Managing an extension](../developer/manage_extension.md). +For managing the `gubbins` extension in development mode, refer to the [Developer Guide: Managing an extension](../../dev/how-to/manage_web_extension.md). ### `gubbins` extension in development mode, as a standalone diff --git a/docs/admin/manage_dependencies.md b/docs/admin/manage_dependencies.md deleted file mode 100644 index b41a18d0..00000000 --- a/docs/admin/manage_dependencies.md +++ /dev/null @@ -1,29 +0,0 @@ -# Managing dependencies - -## Updating dependencies - -[Dependabot](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/managing-pull-requests-for-dependency-updates) is a GitHub-integrated tool that automates dependency management by regularly checking for updates and creating pull requests (PRs) to keep your project's dependencies current. In the `diracx-web` repository, Dependabot is configured to run weekly, generating PRs for any outdated or vulnerable dependencies. - -1. **Review Dependabot PRs:** - - **Access PRs:** Navigate to the repository's "Pull Requests" section to view Dependabot's submissions. - - **Examine Changes:** Assess the proposed updates, paying close attention to any major version changes that might introduce breaking changes. - -2. **Verify Test Results:** - - **Automated Tests:** Ensure that all continuous integration (CI) checks and automated tests pass successfully for each Dependabot PR. - - **Handle Failures:** If tests fail, investigate the cause by reviewing the dependency's changelog or release notes to identify any breaking changes or incompatibilities. - -3. **Adapt Code if Necessary:** - - **Local Checkout:** Check out the PR branch locally. - - **Implement Fixes:** Modify the codebase to address any issues introduced by the dependency update. - - **Test Changes:** Run the test suite locally to confirm that your changes resolve the issues. - - **Push Updates:** After making the necessary adjustments, commit and push your changes to the Dependabot branch. - -4. **Merge PRs:** - - **Final Review:** Once tests pass and the codebase is stable, proceed to merge the PR into the main branch. - - **Post-Merge Actions:** Monitor the application post-deployment to ensure that the update does not introduce any unforeseen issues. - -## Managing Security Vulnerabilities - -Dependabot also helps in identifying and addressing security vulnerabilities in your project's dependencies. When a vulnerability is detected, Dependabot generates alerts and can automatically create PRs to update the affected dependencies. - -Navigate to the repository's "Security" tab and select "Dependabot alerts" to view any security vulnerabilities identified in the dependencies. diff --git a/docs/dev/how-to/contribute_to_web.md b/docs/dev/how-to/contribute_to_web.md new file mode 100644 index 00000000..cf2aec74 --- /dev/null +++ b/docs/dev/how-to/contribute_to_web.md @@ -0,0 +1,35 @@ +# Contributing to DiracX-Web + +*Requirements: [Setup Environment](setup_web_environment.md)* + +=== "Documentation" + + Ensure that any code you write is well-documented. This includes: + + - Inline comments where necessary to explain complex logic. + - Updating or creating Storybook documentation if you are contributing to the `diracx-web-components` library. + - You can use tools like [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/) to maintain code quality. + +=== "Testing" + + **Component Testing** + : Write tests for your stories to ensure they work as expected. Use [Jest](https://jestjs.io/) for unit testing and snapshot testing of your React components. + + **Application Testing** + : Use [Cypress](https://www.cypress.io/) for end-to-end testing to simulate real user interactions and ensure your application behaves correctly. + + **Test Coverage** + : Maintain good test coverage to ensure that your critical features are well-protected during updates. Tools like Jest provide [coverage reports](https://jestjs.io/docs/code-coverage) that help you identify untested parts of your code. + +=== "Accessibility" + + Make your application accessible to all users. Use semantic HTML, ARIA attributes, and test your application with different screen sizes and assistive technologies. + +!!! note + If you create an export function or component in `diracx-web-components`, you must add it to the `index.ts` file and run `npm run build` inside `packages/diracx-web-components` to ensure the pre-commit hook passes. + +!!! warning + Don't forget to update the `packages/extensions` code if you integrate breaking changes in the `diracx-web-components` library. See [Managing the extension](manage_web_extension.md) for further details. + +!!! note "Pre-commit Hooks" + `Husky` is configured to run as a pre-commit script, executing tasks such as linting staged files to maintain code consistency with the codebase. diff --git a/docs/dev/how-to/create_application.md b/docs/dev/how-to/create_web_application.md similarity index 90% rename from docs/dev/how-to/create_application.md rename to docs/dev/how-to/create_web_application.md index 0b23ac46..5f3bb696 100644 --- a/docs/dev/how-to/create_application.md +++ b/docs/dev/how-to/create_web_application.md @@ -14,7 +14,8 @@ You must provide: - An icon that will appear in the `Add application` menu - An optional function, `validateAndConvertState`, which identifies and corrects the structure of a JSON pasted by the user during import. This function ensures compatibility between versions by transforming the pasted state into a valid, updated version. It should be reviewed and updated in any version that modifies the exported/imported state structure -πŸ’‘You can look at the type `ApplicationMetadata` for more details +!!! tip + You can look at the type `ApplicationMetadata` for more details. ### Code the application @@ -22,4 +23,5 @@ The code of your app should be in `packages/diracx-web-components/src/components In order to be compatible with the share and import buttons, the application must write its state to the session storage at `_State`. This slot is read from and written to by the corresponding functions. -πŸ’‘You can look at `JobMonitor` as an example. +!!! tip + You can look at `JobMonitor` as an example. diff --git a/docs/dev/manage_extension.md b/docs/dev/how-to/manage_web_extension.md similarity index 82% rename from docs/dev/manage_extension.md rename to docs/dev/how-to/manage_web_extension.md index be82b526..2773cce1 100644 --- a/docs/dev/manage_extension.md +++ b/docs/dev/how-to/manage_web_extension.md @@ -81,12 +81,5 @@ export DIRACX_URL= npm run --prefix packages/extensions test ``` -### `gubbins` (backend) - -Follow the instructions from the [Gubbins extension README](https://github.com/DIRACGrid/diracx/tree/main/extensions#work-on-gubbins). - -:bulb: Like `diracx-web`, `gubbins-web` does automatically reflect changes made in `diracx-web-components`. This means that while running `gubbins` using `diracx-charts/run_demo.sh`, any modifications to `diracx-web-components` will also be applied to `gubbins`. - -## Creating a new extension - -More details available in the [**extensions** README](/packages/extensions/README.md) \ No newline at end of file +!!! tip + Like `diracx-web`, `gubbins-web` does automatically reflect changes made in `diracx-web-components`. This means that while running `gubbins` using `diracx-charts/run_demo.sh`, any modifications to `diracx-web-components` will also be applied to `gubbins`. diff --git a/docs/dev/setup_environment.md b/docs/dev/how-to/setup_web_environment.md similarity index 90% rename from docs/dev/setup_environment.md rename to docs/dev/how-to/setup_web_environment.md index b7ed381a..112c54cf 100644 --- a/docs/dev/setup_environment.md +++ b/docs/dev/how-to/setup_web_environment.md @@ -140,7 +140,8 @@ git clone git@github.com:DIRACGrid/diracx-charts.git diracx-charts/run_demo.sh ./diracx-web [./diracx] ``` -:bulb: Any change made in `diracx-web-components` are automatically reflected into the development environment. We rely on the [NextJS transpile option](https://nextjs.org/docs/app/api-reference/config/next-config-js/transpilePackages). Further details are available in the `diracx-web` NextJS configuration. +!!! tip + Any change made in `diracx-web-components` is automatically reflected into the development environment. We rely on the [NextJS transpile option](https://nextjs.org/docs/app/api-reference/config/next-config-js/transpilePackages). Further details are available in the `diracx-web` NextJS configuration. ## Testing @@ -160,12 +161,8 @@ npm run --prefix packages/diracx-web test ## Documenting -[Storybook]((https://storybook.js.org/docs)) can be started with: +[Storybook](https://storybook.js.org/docs) can be started with: ```bash npm run doc:diracx-web-components ``` - -## Contributing - -See the [Contributing guidelines](/CONTRIBUTING.md) \ No newline at end of file diff --git a/docs/dev/reference/web-arch.md b/docs/dev/reference/web-arch.md new file mode 100644 index 00000000..0317a7e4 --- /dev/null +++ b/docs/dev/reference/web-arch.md @@ -0,0 +1,74 @@ +# Web Architecture + +## Monorepo Structure + +The DiracX-Web repository is organized as a monorepo using [npm workspaces](https://docs.npmjs.com/cli/v10/using-npm/workspaces). Local packages are resolved from their workspace versions rather than the npm registry. + +```mermaid +--- +config: + layout: elk +--- +flowchart TD + subgraph monorepo["Monorepo"] + components["diracx-web-components"] + web["diracx-web"] + extensions["extensions (gubbins)"] + end + web -. uses .-> components + extensions -. uses .-> components + components -- published on --> npm["npm registry"] + community["Community extensions"] -. uses .-> npm +``` + +## Packages + +### diracx-web-components + +- **Purpose**: Reusable React component library. +- **Build tool**: [tsup](https://tsup.egoist.dev/) for TypeScript compilation. +- **Design system**: [Material-UI (MUI)](https://mui.com/). +- **Documentation**: [Storybook](https://storybook.js.org/). +- **Testing**: [Jest](https://jestjs.io/) + [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/). +- **Exports**: Components, contexts, hooks, and types as separate modules. + +### diracx-web + +- **Purpose**: Vanilla DiracX web interface. +- **Framework**: [Next.js 15](https://nextjs.org/) with App Router. +- **Output**: Static export (`output: "export"`). +- **Authentication**: [@axa-fr/react-oidc](https://github.com/AxaFrance/oidc-client). +- **Testing**: [Cypress](https://www.cypress.io/) for end-to-end tests. +- **Serving**: Nginx in production (Docker image). + +### extensions (gubbins) + +- **Purpose**: Reference example of a custom DiracX web extension. +- **Framework**: Next.js, same setup as `diracx-web`. +- **Demonstrates**: How to extend the application list, add custom components, and deploy as a standalone project. + +## Key Directories + +| Path | Description | +|---|---| +| `packages/diracx-web-components/src/components/` | Reusable UI components | +| `packages/diracx-web-components/src/contexts/` | React contexts for state management | +| `packages/diracx-web-components/src/hooks/` | Custom React hooks | +| `packages/diracx-web-components/src/types/` | TypeScript type definitions | +| `packages/diracx-web/src/app/` | Next.js App Router pages and layouts | +| `packages/extensions/src/` | Extension source (gubbins example) | + +## Routing + +DiracX-Web uses [Next.js folder-based routing](https://nextjs.org/docs/app/building-your-application/routing): + +- `src/app/(dashboard)/` β€” Main dashboard (parentheses are ignored in the route, so this is the root URL). +- `src/app/auth/` β€” Authentication pages, served at `/auth`. +- `page.tsx` files define the UI for a route. +- `layout.tsx` files define shared UI for a segment and its children. + +## State Management + +- **Application state**: Managed via React Context (`ApplicationProvider`). +- **Session storage**: Each application instance writes its state to `_State` for share/import functionality. +- **URL encoding**: Dashboard layout is encoded in the URL for sharing. diff --git a/docs/dev/tutorials/web_extensions.md b/docs/dev/tutorials/web_extensions.md new file mode 100644 index 00000000..4484f55a --- /dev/null +++ b/docs/dev/tutorials/web_extensions.md @@ -0,0 +1,235 @@ +# Creating a DiracX Web Extension + +![CI](https://github.com/DIRACGrid/diracx-web/actions/workflows/gubbins-test.yml/badge.svg?branch=main) + +This project aims to provide an example for creating a basic Next.js web extension for DiracX. It includes the necessary configuration and setup to get you started quickly. + +## Prerequisites + +Before starting, ensure you have the following installed: + +- [Docker](https://www.docker.com/get-started) +- [Node.js](https://nodejs.org/) +- [Git](https://git-scm.com/) + +And ensure you have basic knowledge of: + +- [React](https://react.dev/) +- [Next.js](https://nextjs.org/) +- [MUI](https://mui.com/) + +## Getting Started + +You can either create a new repository or start from this one to build your DiracX extension. Follow one of the methods below: + +### Method 1: Fork the Repository + +1. **Clone this repository** on GitHub, move and rename the `diracx-web/packages/extensions` directory: + + ```bash + git clone https://github.com/DIRACGrid/diracx-web.git + mv diracx-web/packages/extensions + cd + ``` + +2. **Slightly modify the `package.json` file** + + From ``, execute the following command: + + ```bash + # Adapt the path of the copy-service-worker-files script + jq '.scripts.postinstall = "node ./node_modules/@axa-fr/react-oidc/bin/copy-service-worker-files.mjs public"' ./package.json > ./package.temp.json + mv ./package.temp.json ./package.json + # Adapt the package name and version + jq '.name = ""' ./package.json > ./package.temp.json + mv ./package.temp.json ./package.json + jq '.version = "0.1.0-a0"' ./package.json > ./package.temp.json + mv ./package.temp.json ./package.json + ``` + +3. **Remove `CHANGELOG.md`** + +### Method 2: Create a New Next.js Project + +1. **Create a new Next.js project** using the following command: + + ```bash + npx create-next-app your-extension + cd your-extension + ``` + +2. **Add the DiracX Web Components Library** to your project: + + ```bash + npm install @dirac-grid/diracx-web-components + ``` + + To include additional dependencies in your project, such as `cypress` for end-to-end tests, you can follow these steps: + + Run the following command to install the desired dependency: + + ```bash + npm install + ``` + + Add the `--save-dev` or `-D` flag to install the dependency as a development dependency. + + Replace `` with the name of the dependency you want to install. + + For example, to install `cypress`, run: + + ```bash + npm install cypress -D + ``` + + Make sure to consult the documentation of each dependency for further instructions on how to use them in your project. + + For `cypress`, you can refer to the [Cypress documentation](https://docs.cypress.io/guides/overview/why-cypress.html) for detailed usage instructions. + +3. **Add the OIDC postinstall script** to your `package.json` file to copy necessary service worker files: + + ```json + "scripts": { + "postinstall": "node ./node_modules/@axa-fr/react-oidc/bin/copy-service-worker-files.mjs public" + } + ``` + + This is needed to update the service worker files when the OIDC library version changes. + + See the [OIDC library documentation](https://github.com/AxaFrance/oidc-client/tree/main/packages/react-oidc#getting-started) for more information. + + Note: for backendless local development, replace the `dev` command by: + + ```json + "scripts": { + "dev": "export NEXT_PUBLIC_DIRACX_URL=$DIRACX_URL; next dev", + ... + } + ``` + + This avoids having to set 2 environment variables with the same value: NextJS can only read from variables prefixed with `NEXT_PUBLIC`. + +4. **Edit the Next.js config** with these options: + + ```js + output: "export", + images: { + unoptimized: true, + }, + ``` + + The output is set to `export` to have a static application. + Images are left unoptimized because it's not well-supported with a static export. + +5. **Add the nginx config** located in the [`config/nginx`](config/nginx/) directory. + This adjustment ensures that Nginx can correctly handle requests for .html files and fall back appropriately, preventing the `404: Not Found` errors encountered when accessing routes like `/auth`. (see [#57](https://github.com/DIRACGrid/diracx-web/pull/57)) + +6. **Organize your pages** in the `src/app` app directory. + The `` context is needed by most of the components of `diracx-web-components`, so you should include it in the layouts of your application. Use `` to require authentication on a route. You can also override some default values of certain contexts like `` for the application list. + Finally, some components have some personalization options (i.e. the logo URL for the dashboard), check the [Storybook documentation](https://diracgrid.github.io/diracx-web/) to see the props of each component. + Check [the app directory](src/app/) in this example to have a reference. + +### Architecture + +We strongly recommend following the directory structure below to keep your project organized: + +- `/src/app`: Contains the main application logic and Next.js setup. This directory houses the core of the application built using Next.js, where each page.tsx file represents a page in the application with [folder-based routing](https://nextjs.org/docs/app/building-your-application/routing). [Next.js Official Documentation](https://nextjs.org/docs). + The page.tsx files contain the UI for a route and layout.tsx files handles the shared UI for a segment and its children. + In this example the `(Dashboard)` folder manages the main interface where users interact with the app's primary functions. Names in parentheses are ignored for the route, so it is the root URL. + The `auth` folder handles the authentication of users, and the route is `/auth`. + +- `/src/`: This directory includes the source code related to your extension. You can create custom components, hooks, ... in this directory. + - `/src//components`: Contains custom React components. This folder includes reusable UI components built using React. Components in React are independent, reusable pieces of UI that can manage their own state. [React Components](https://reactjs.org/docs/components-and-props.html) + - `/src//contexts`: Manages global state using React Context. This folder contains context providers which are used to manage and share global state across the application. React Context provides a way to pass data through the component tree without having to pass props down manually at every level. [React Context](https://reactjs.org/docs/context.html) + - `/src//hooks`: Custom React hooks for encapsulating reusable logic. This directory includes custom hooks. Hooks are special functions that let you "hook into" React state and lifecycle features from function components. [React Hooks](https://reactjs.org/docs/hooks-intro.html) + - `/src//types`: TypeScript type definitions for the application. This folder contains TypeScript type definitions to ensure type safety throughout the application. + +### Running the Extension with DiracX Charts + +To start your DiracX extension in development mode follow these steps: + +1. **Clone the `diracx-charts` repository** in a parent directory: + + ```bash + git clone git@github.com:DIRACGrid/diracx-charts.git + ``` + +2. **Run the demo script** with the path to your extension: + + ```bash + ./diracx-charts/run_demo.sh path/to/your-extension + ``` + +To run your extension in a production environment, you need to customize the [`diracx` Helm Chart](https://github.com/DIRACGrid/diracx-charts) values, such as: + +```yaml +global.images.web.tag: +global.images.web.repository: +``` + +## Customizing the Extension + +You can customize your extension by modifying the files in the `src` directory. This is where you’ll find the main components and logic of your extension. + +Having a directory dedicated to your extension components will help you keep your code organized and easy to maintain. + +### Extending the DiracX Apps + +To add new apps to your extension, you can create new components in your extension directory. + +[`testApp`](src/gubbins/components/TestApp/testApp.tsx) provides an example of a basic app component and the [Storybook documentation](https://diracgrid.github.io/diracx-web/) showcases all the components you can use from the library in an interactive interface. + +It is then pretty easy to add them to DiracX Web by extending the `applicationList` (the list of apps available in DiracX-Web) from `diracx-web-components/components`. + +Context providers are used to manage and share global state across the application. You can use the `ApplicationProvider` from `diracx-web-components/contexts` to pass the list of applications to the components that need it. +It is used in this example in the [(Dashboard) directory's layout.tsx]() file. + +If you need more info on Contexts, you can check the [React documentation](https://reactjs.org/docs/context.html). + +```tsx +// import the Application Context Provider and the default application list from the library +import { ApplicationProvider } from "@dirac-grid/diracx-web-components/contexts"; +import { applicationList } from "@dirac-grid/diracx-web-components/components"; + +// The new Application you want to add +const newApp = { + name: "New App", // Its name + icon: new-app-icon, // An icon for the app, you can import some from "@mui/icons-material" + component: NewAppComponent, // The component you made for your Application +}; + +// Make a new list with all elements of the default list + the new application +const newApplicationList = [...applicationList, newApp]; + +// Use your new list by passing in the Application provider in a page's layout +...; +``` + +In this example, the new App list is defined in a [separate file](src/gubbins/applicationList.ts) + +Feel free to explore and adjust the code to fit your requirements. + +## Deployment + +Deployment of the extension can be done using the Dockerfile provided in the repository. The Dockerfile builds the Next.js application and serves it using a nginx server. + +See [Docker's Documentation](https://docs.docker.com/get-started/) for more information on how to deploy your application using Docker. +It can be automatically deployed using CI/CD tools like GitHub Actions, GitLab CI/CD, or Jenkins. + +## Good Practices + +- **Code Quality**: Ensure your code is clean, well-documented, and follows best practices. Use tools like [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/) to maintain code quality. + +- **Testing**: + - **Component Testing**: Write tests for your components to ensure they work as expected. Use [Jest](https://jestjs.io/) for unit testing and snapshot testing of your React components. + - **Application Testing**: Use [Cypress](https://www.cypress.io/) for end-to-end testing to simulate real user interactions and ensure your application behaves correctly. + - **Test Coverage**: Maintain good test coverage to ensure that your critical features are well-protected during updates. Tools like Jest provide [coverage reports](https://jestjs.io/docs/code-coverage) that help you identify untested parts of your code. + +- **Accessibility**: Make your extension accessible to all users. Use semantic HTML, ARIA attributes, and test your extension with different screen sizes and assistive technologies. + +- **Security**: + - **Dependency Management**: Keeping dependencies up to date is crucial for security and performance. Using deprecated packages can expose your application to known vulnerabilities. + - **Identifying Vulnerabilities**: Regularly check for known vulnerabilities in your dependencies. Tools like [`npm audit`](https://docs.npmjs.com/cli/v7/commands/npm-audit) can help spot these issues. + - **Automating Updates**: Use tools like [Dependabot](https://github.com/dependabot) or [Renovate](https://www.whitesourcesoftware.com/free-developer-tools/renovate/) to automate dependency updates. These tools can automatically create pull requests to update dependencies, making it easier to stay current and see if updates are compatible with tests used in CI. Keeping dependencies up to date is crucial for security as deprecated packages can expose your application to known vulnerabilities. + +By following these practices, you'll ensure that your codebase remains robust, secure, and maintainable. diff --git a/docs/dev/web-arch.md b/docs/dev/web-arch.md deleted file mode 100644 index 337d17ef..00000000 --- a/docs/dev/web-arch.md +++ /dev/null @@ -1,54 +0,0 @@ - -# Developer Guide - -Welcome to the DiracX-Web Developer Guide! This guide will help you navigate and ramp you up. Adding features, fixing the code in a consistent manner with tests and documentation will become a second nature. - - -## Architecture Overview - -```mermaid ---- -config: - layout: elk ---- -flowchart TD - subgraph monorep["Monorepo"] - monorep1["diracx-web-components"] - monorep2["diracx-web"] - monorep3["extension[gubbins]"] - end - monorep2 -- images deployed in --> docker[" "] - monorep2 -. uses .-> monorep1 - monorep3 -. uses .-> monorep1 - monorep1 -- documented on --> storybook[" "] - monorep1 -- published on --> npm[" "] - extension["diracx-community-extension"] -. uses .-> npm - docker@{ img: "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQLQKd_MRed_mZQlgrzQuUXVA3P39ssOVX8_g&s", h: 100, w: 100} - storybook@{ img: "https://miro.medium.com/v2/resize:fit:900/1*ZuBTYHXl6l3XzTb8d9Oi5Q.png", h: 100, w: 150, pos: "b"} - npm@{ img: "https://upload.wikimedia.org/wikipedia/commons/thumb/d/db/Npm-logo.svg/2560px-Npm-logo.svg.png", h: 40, w: 100} - monorep1:::Ash - monorep1:::Cyan - monorep2:::Green - monorep3:::Green - extension:::Ash - classDef Cyan stroke-width:1px, stroke-dasharray:none, stroke:#00FFFF, fill:#9CFFFF - classDef Green stroke-width:1px, stroke-dasharray:none, stroke:#5BFF00, fill:#A4FF8E, color:#374D7C - classDef Ash stroke-width:1px, stroke-dasharray:none, stroke:#999999, fill:#EEEEEE, color:#000000 -``` - -This repository is organized as a monorepo, with the following key packages: - -- [**DiracX-Web-Components**](packages/diracx-web-components): A library of reusable React components designed for integration within the `DiracX-Web` package and to facilitate the creation of custom DiracX web extensions. - -- [**DiracX-Web**](packages/diracx-web): Vanilla Dirac web interface based on Next.js. Leverages components from `DiracX-Web-Components` to provide core functionalities. - -- [**Extensions**](packages/extensions): An illustrative example of a web extension, also based on Next.js, demonstrating how to extend the functionality of `DiracX-Web` using the components from the `DiracX-Web-Components` package. - - -The monorepo structure is based on *npm workspaces* to ensure that related packages ([DiracX-Web-Components](packages/diracx-web-components)) are automatically used from their local versions instead of fetching them from the npm registry. - -## Ramping up - -- [Set up a development environment](setup_environment.md) -- [Manage the extension](manage_extension.md) -- [Contribute to the effort](../developer/contribute.md) diff --git a/docs/developer/contribute.md b/docs/developer/contribute.md deleted file mode 100644 index 7b6a2110..00000000 --- a/docs/developer/contribute.md +++ /dev/null @@ -1,55 +0,0 @@ -# Contributing to DiracX-Web - -### 1. Open an Issue - -- **Discuss Before Implementing:** Before making a pull request (PR), especially for non-trivial changes, please [open an issue](https://github.com/DIRACGrid/diracx-web/issues) to discuss your idea. This ensures that everyone is aligned on the proposed change. -- **Check for Existing Issues:** Before opening a new issue, please check if a similar issue already exists. If a similar issue exists, consider contributing to the discussion there instead. - -**Good to know:** If you want to start contributing right away, check out the issues labeled with ["good first issue"](https://github.com/DIRACGrid/diracx-web/labels/good%20first%20issue). These are issues that - in principle - are well-suited for newcomers to the project. - -### 2. Make Changes - -*Requirements: [Setup Environment](setup_environment.md)* - -- **Fork the Repository:** Start by forking the repository and creating a new branch for your work. Use a descriptive name for your branch that reflects the work you are doing. - -- **Code Documentation:** Ensure that any code you write is well-documented. This includes: - - Inline comments where necessary to explain complex logic. - - Updating or creating Storybook documentation if you are contributing to the `diracx-web-components` library. - - You can use tools like [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/) to maintain code quality. - -- **Testing**: - - - **Component Testing**: Write tests for your stories to ensure they work as expected. Use [Jest](https://jestjs.io/) for unit testing and snapshot testing of your React components. - - **Application Testing**: Use [Cypress](https://www.cypress.io/) for end-to-end testing to simulate real user interactions and ensure your application behaves correctly. - - **Test Coverage**: Maintain good test coverage to ensure that your critical features are well-protected during updates. Tools like Jest provide [coverage reports](https://jestjs.io/docs/code-coverage) that help you identify untested parts of your code. - -- **Accessibility**: Make your application accessible to all users. Use semantic HTML, ARIA attributes, and test your application with different screen sizes and assistive technologies. - -By following these practices, you'll ensure that your codebase remains robust, secure, and maintainable. - -**Good to know:** If you create an export function or component in `diracx-web-components`, you must add it to the `index.ts` file and run `npm run build` inside `packages/diracx-web-components` to ensure the pre-commit hook passes. - -**Note:** Don't forget to update the `packages/extensions` code if you integrate breaking changes in the `diracx-web-components` library. See [Managing the extension](manage_extension.md) for further details. - -### 3. Commit - -- **Conventional Commits:** All commits must follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. This ensures that commit messages are structured and consistent, which is important for automation and versioning. - - **Examples:** - - `feat(ui): add new button component` - - `fix(api): handle null values in response` - - `docs(readme): update contributing guidelines` - - **Why?** If your commit messages do not follow this convention, the Continuous Integration (CI) process will fail, and your PR will not be merged. Please ensure your commit messages are properly formatted before pushing. - -- **Note**: `Husky` is configured to run as a pre-commit script, executing tasks such as linting staged files to maintain code consistency with the codebase. - - -### 4. Make a Pull Request (PR) - -- **Submit Your PR:** When you’re ready, submit your pull request. Please include a clear description of what your PR does and reference the issue number it addresses (if applicable). -- **Review Process:** Your PR will be reviewed by project maintainers. Please be patient and responsive to any feedback you receive. - -### 5. Additional Notes - -- **Trivial Changes:** For minor changes like fixing typos, feel free to skip the issue creation step and go straight to making a PR. -- **Stay Up-to-Date:** Make sure your branch is up-to-date with the latest changes in the main branch before submitting your PR. Use `git rebase` if necessary. \ No newline at end of file diff --git a/docs/developer/manage_extension.md b/docs/developer/manage_extension.md deleted file mode 100644 index 9d7f3f12..00000000 --- a/docs/developer/manage_extension.md +++ /dev/null @@ -1,147 +0,0 @@ -# Managing Extensions - -This guide explains how to manage and develop extensions for DiracX Web. - -## What are Extensions? - -Extensions in DiracX Web allow you to add custom functionality and pages without modifying the core application. They are built as separate packages that integrate with the main application. - -## Extension Structure - -Extensions follow a specific structure: - -``` -my-extension/ -β”œβ”€β”€ package.json -β”œβ”€β”€ src/ -β”‚ β”œβ”€β”€ components/ -β”‚ β”œβ”€β”€ pages/ -β”‚ └── index.ts -└── README.md -``` - -## The Gubbins Extension - -The `gubbins` extension serves as a reference implementation and template for creating new extensions. - -### Development Setup - -To work with the gubbins extension in development mode: - -1. **Navigate to the extensions directory:** - ```bash - cd packages/extensions - ``` - -2. **Install dependencies:** - ```bash - npm install - ``` - -3. **Start development with the extension:** - ```bash - npm run dev:with-extensions - ``` - -### Creating a New Extension - -1. **Use the gubbins extension as a template:** - ```bash - cp -r packages/extensions/gubbins packages/extensions/my-extension - ``` - -2. **Update the package.json:** - ```json - { - "name": "@diracx-web/my-extension", - "version": "0.1.0", - "description": "My custom DiracX extension" - } - ``` - -3. **Register the extension:** - Add your extension to the main application's configuration. - -## Extension API - -Extensions can leverage the following APIs: - -### Page Registration - -Register new pages in your extension: - -```typescript -export const pages = [ - { - path: '/my-feature', - component: MyFeatureComponent, - title: 'My Feature' - } -]; -``` - -### Component Registration - -Register reusable components: - -```typescript -export const components = { - MyCustomComponent, - AnotherComponent -}; -``` - -## Building Extensions - -### Development Build - -For development with hot reload: - -```bash -npm run build:dev -``` - -### Production Build - -For optimized production builds: - -```bash -npm run build -``` - -## Testing Extensions - -Test your extension: - -```bash -npm run test:extension my-extension -``` - -## Deployment - -### As Part of Main Application - -Extensions built with the main application are included automatically. - -### Standalone Deployment - -For standalone deployment: - -1. Build the extension separately -2. Configure the hosting environment -3. Update the main application to load the remote extension - -## Best Practices - -1. **Keep extensions lightweight** - Only include necessary dependencies -2. **Follow naming conventions** - Use consistent naming for components and pages -3. **Document thoroughly** - Provide clear README and inline documentation -4. **Test comprehensively** - Include unit and integration tests - -## Troubleshooting - -### Common Issues - -- **Import errors:** Ensure all dependencies are correctly declared -- **Build failures:** Check for TypeScript errors and missing dependencies -- **Runtime errors:** Verify component registration and routing configuration \ No newline at end of file diff --git a/docs/developer/setup_environment.md b/docs/developer/setup_environment.md deleted file mode 100644 index 53260a16..00000000 --- a/docs/developer/setup_environment.md +++ /dev/null @@ -1,99 +0,0 @@ -# Setting up your Development Environment - -This guide explains how to set up a development environment for DiracX Web. - -## Prerequisites - -- Node.js (version 18 or higher) -- npm or yarn package manager -- Git - -## Quick Start - -1. **Clone the repository:** - ```bash - git clone https://github.com/DIRACGrid/diracx-web.git - cd diracx-web - ``` - -2. **Install dependencies:** - ```bash - npm install - ``` - -3. **Start the development server:** - ```bash - npm run dev - ``` - -The development server will start on `http://localhost:3000` by default. - -## Development Workflow - -### File Structure - -The main directories in the project: -- `packages/` - Contains all the packages (components, main web app, extensions) -- `public/` - Static assets -- `docs/` - Documentation - -### Running in Development Mode - -When running in development mode: -- Hot reload is enabled for instant feedback -- Source maps are available for debugging -- Development-specific features are enabled - -### Environment Configuration - -Create a `.env.local` file in the root directory to configure environment variables: - -```bash -# DiracX API endpoint -NEXT_PUBLIC_DIRACX_URL=http://localhost:8000 - -# OIDC configuration -NEXT_PUBLIC_OIDC_AUTHORITY=your-oidc-authority -NEXT_PUBLIC_OIDC_CLIENT_ID=your-client-id -``` - -## Building for Production - -To build the application for production: - -```bash -npm run build -``` - -This creates an optimized production build in the `.next` directory. - -## Testing - -Run the test suite: - -```bash -npm test -``` - -For continuous testing during development: - -```bash -npm run test:watch -``` - -## Troubleshooting - -### Common Issues - -1. **Port already in use:** The default port 3000 might be occupied. Use a different port: - ```bash - npm run dev -- -p 3001 - ``` - -2. **Module not found:** Clear node_modules and reinstall: - ```bash - rm -rf node_modules package-lock.json - npm install - ``` - -For more detailed information, see the [CONTRIBUTING.md](/CONTRIBUTING.md) file. \ No newline at end of file diff --git a/docs/user/how-to/index.md b/docs/user/how-to/index.md index e69de29b..e6a4754e 100644 --- a/docs/user/how-to/index.md +++ b/docs/user/how-to/index.md @@ -0,0 +1,9 @@ +# DiracX Web + +DiracX Web is the graphical interface for interacting with DiracX services through your browser. It allows you to monitor jobs, manage applications, and access DiracX functionalities without using the command line. + +## Guides + +- [Logging in & out](login_out.md) β€” How to authenticate and access your dashboard. +- [Managing application instances](list_and_share_applications.md) β€” How to add, organize, group, share, and import applications. +- [Monitor jobs](monitor_jobs.md) β€” How to search, filter, and act on jobs using the Job Monitor. diff --git a/docs/user/web/list_and_share_applications.md b/docs/user/how-to/list_and_share_applications.md similarity index 59% rename from docs/user/web/list_and_share_applications.md rename to docs/user/how-to/list_and_share_applications.md index 4dd03d8a..5eff6ca7 100644 --- a/docs/user/web/list_and_share_applications.md +++ b/docs/user/how-to/list_and_share_applications.md @@ -9,21 +9,34 @@ By default, a few application instances are displayed (e.g., `My Jobs`, an insta ### Accessing More Applications 1. Click the **Add Application** button at the bottom of the sidebar. - - :bulb: On mobile devices, first open the sidebar by clicking the **menu icon** (☰) at the top-left corner. + + !!! tip + On mobile devices, first open the sidebar by clicking the **menu icon** (☰) at the top-left corner. + 2. Select an application from the list in the dialog box. - - :bulb: The selected application will appear in the sidebar. + + !!! tip + The selected application will appear in the sidebar. ### Opening Multiple Instances of the Same Application - Repeat the steps above to open additional instances of the same application. - - :bulb: Each instance has its own state, making it ideal for monitoring different job groups with specific criteria for instance. + + !!! tip + Each instance has its own state, making it ideal for monitoring different job groups with specific criteria for instance. ### Renaming an Application Instance 1. **Right-click** on the instance name in the sidebar. - - :bulb: A context menu will appear. + + !!! tip + A context menu will appear. + 2. Select **Rename**. - - :bulb: The instance name will change to an input field. + + !!! tip + The instance name will change to an input field. + 3. Enter a new name and press **Enter** to save it. ### Moving an Application Instance @@ -36,19 +49,32 @@ By default, a few application instances are displayed (e.g., `My Jobs`, an insta ### Deleting an Application Instance 1. **Right-click** on the instance name in the sidebar. - - :bulb: A context menu will appear. + + !!! tip + A context menu will appear. + 2. Select **Delete**. - - :bulb: The application instance will disappear from the sidebar. + + !!! tip + The application instance will disappear from the sidebar. ### Sharing Your Dashboard 1. Copy the URL from your browser. - - :bulb: The URL encodes the current state of your dashboard. + + !!! tip + The URL encodes the current state of your dashboard. + 2. Share it with others. - - :warning: The recipient will see a similar dashboard layout but may not see identical content if: - - They belong to a different VO or group. - - Time-sensitive data has changed since sharing. - - :warning: Encoding too many application instances may create discrepancies as the URL has a theoretical limit of 8000 characters based on [RFC9110](https://www.rfc-editor.org/rfc/rfc9110#section-4.1-5) + + !!! warning + The recipient will see a similar dashboard layout but may not see identical content if: + + - They belong to a different VO or group. + - Time-sensitive data has changed since sharing. + + !!! warning + Encoding too many application instances may create discrepancies as the URL has a theoretical limit of 8000 characters based on [RFC9110](https://www.rfc-editor.org/rfc/rfc9110#section-4.1-5). ## Advanced Features @@ -57,18 +83,32 @@ When managing multiple instances of the same application, grouping can help you ### Creating a New Group 1. **Right-click** anywhere in the sidebar. - - :bulb: A context menu will appear. + + !!! tip + A context menu will appear. + 2. Select **New Group**. - - :bulb: A new group with a default name will appear in the sidebar. + + !!! tip + A new group with a default name will appear in the sidebar. + 3. Add new application instances to the group using the **Add Application** button. - - :bulb: By default, new instances will be placed in the most recently created group. + + !!! tip + By default, new instances will be placed in the most recently created group. ### Renaming a Group 1. **Right-click** on the group name in the sidebar. - - :bulb: A context menu will appear. + + !!! tip + A context menu will appear. + 2. Select **Rename**. - - :bulb: The group name will change to an input field. + + !!! tip + The group name will change to an input field. + 3. Enter a new name and press **Enter** to save it. ### Moving a Group @@ -76,7 +116,10 @@ When managing multiple instances of the same application, grouping can help you 1. Locate the **handle icon** next to the group name. 2. Click and hold the handle to select the group. 3. Drag the group to the desired position within the sidebar. - - :bulb: All application instances within the group will move together. + + !!! tip + All application instances within the group will move together. + 4. Release the mouse button to place the group. ### Moving Instances Between Groups @@ -87,15 +130,20 @@ When managing multiple instances of the same application, grouping can help you ### Deleting a Group 1. **Right-click** on the group name in the sidebar. - - :bulb: A context menu will appear. + + !!! tip + A context menu will appear. + 2. Select **Delete**. - - :bulb: The group and all its application instances will disappear from the sidebar. + !!! tip + The group and all its application instances will disappear from the sidebar. ### Share and import the settings of an application 1. **Share**: You can export the status of an app by clicking on the share button in the top-right corner of the screen. After clicking, you can select which group and app you want to share and then copy a text corresponding to the states of the selected applications. -2. **Import**: Next to the export button you can find the import button. You can paste into the window opened by the button the text corresponding to one or multiple shared apps. This will create a new group named *Imported App* with the imported applications and their settings. +2. **Import**: Next to the export button you can find the import button. You can paste into the window opened by the button the text corresponding to one or multiple shared apps. This will create a new group named *Imported App* with the imported applications and their settings. -**Good to know:** When switching to a new version, the settings you are trying to import may no longer be valid. In this case, a new window will appear, offering to resolve the issue by updating the state copied to your clipboard. This updated version preserves your imported rules as much as possible. +!!! note + When switching to a new version, the settings you are trying to import may no longer be valid. In this case, a new window will appear, offering to resolve the issue by updating the state copied to your clipboard. This updated version preserves your imported rules as much as possible. diff --git a/docs/user/how-to/login_out.md b/docs/user/how-to/login_out.md new file mode 100644 index 00000000..8b7219ed --- /dev/null +++ b/docs/user/how-to/login_out.md @@ -0,0 +1,44 @@ +# Logging in & out + +## Basics + +### Logging in + +1. Go to the DiracX-Web instance homepage. + + !!! tip + You should end up on an authentication page. + +2. Authenticate you as a user of a given VO/group: + - If your instance supports multiple VOs, select your VO in the list box. + - Select your Group in the list box below. + +3. Click the **Login** button. + + !!! tip + You should be redirected to the VO login page. + +4. Enter your credentials (e.g., Username/Password, X509 certificates). + + !!! tip + You should see a page asking for permission to access your profile. + +5. Accept the permissions to access your DiracX dashboard. + + !!! tip + You should be redirected to the DiracX-Web instance as a logged-in user, and the dashboard should appear. + +### Logging out + +1. Click on your profile icon in the top-right corner of the dashboard. + + !!! tip + A dropdown menu should appear. + +2. Select **Logout** from the dropdown menu. + +## Advanced + +### Logging in with specific properties + +TODO diff --git a/docs/user/how-to/monitor_jobs.md b/docs/user/how-to/monitor_jobs.md new file mode 100644 index 00000000..072edf70 --- /dev/null +++ b/docs/user/how-to/monitor_jobs.md @@ -0,0 +1,67 @@ +# Job Monitor documentation + +## The search bar + +The search bar allows you to filter jobs based on various criteria. The filters are represented as equations in the search bar, where each equation consists of a job attribute, an operator, and a value. + +!!! info "Automatic Search" + A search is automatically performed when all the equations in the search bar are valid. + +=== "Create a filter" + + 1. Click on the search bar and start typing + 2. Suggestions will appear based on the available job attributes + 3. Select a suggestion to choose the criterion + 4. Type or select an operator and a value to filter by + + !!! tip "Smart Suggestions" + The search bar only suggests attributes, operators, and values that are available in your current set of jobs. + +=== "Edit a filter" + + - Click on the filter in the search bar to edit it + - Change the operator or value by clicking on them + - Use the arrow keys to navigate through the equations and edit them + +=== "Remove a filter" + + - Press the `Backspace` key to remove the last token + - Right-click on the equation to remove the entire equation + + +## Use the table + +By default, the jobs are displayed in a table. If you are viewing them in another chart, you can click the table button next to the search bar to switch back to the table view. + +The table displays the jobs that match the criteria specified in the search bar. Each row represents a job, and the columns show various attributes of the job, such as its ID, status, type, and submission date. + +=== "Table Management" + + **Column Selection** + : Click on the eye icon to select more columns to display in the table. + + **Sorting** + : Click on column headers to sort the table. First click sorts ascending, second click sorts descending. + + **Page Size** + : Use the `Row per page` dropdown at the bottom of the table to control how many jobs are displayed per page. + +=== "Job Actions" + + **View Job Details** + : Right-click on a job to open the `Job History`. + + **Bulk Actions** + : Select one or more jobs using the checkboxes, then use the action buttons: + + - **Get IDs**: Copy the IDs of selected jobs to clipboard + - **Reschedule**: Reschedule the selected jobs + - **Kill**: Kill the selected jobs + - **Delete**: Delete the selected jobs + + !!! warning "Destructive Actions" + Be careful when using Kill or Delete actions as they cannot be undone. + +## Use the Pie Chart + +You can change the visualization to use a pie chart with the button next to the search bar. The pie chart provides a hierarchical view of the jobs based on their attributes. The `Columns to plot` component lets you choose your criteria for visualizing the jobs. The chart can display two levels, and you can then click on a section of the chart to zoom into that category and see more details. diff --git a/docs/user/web/index.md b/docs/user/web/index.md deleted file mode 100644 index ea2d95d0..00000000 --- a/docs/user/web/index.md +++ /dev/null @@ -1 +0,0 @@ -# DiracX Web diff --git a/docs/user/web/login_out.md b/docs/user/web/login_out.md deleted file mode 100644 index 1c8fab94..00000000 --- a/docs/user/web/login_out.md +++ /dev/null @@ -1,28 +0,0 @@ -# Logging in & out - -## Basics - -### Logging in - -1. Go to the DiracX-Web instance homepage. - - πŸ’‘ You should end up on an authentication page. -2. Authenticate you as a user of a given VO/group: - - If your instance supports multiple VOs, select your VO in the list box. - - Select your Group in the list box below. -3. Click the **Login** button. - - πŸ’‘ You should be redirected to the VO login page. -4. Enter your credentials (e.g., Username/Password, X509 certificates). - - πŸ’‘ You should see a page asking for permission to access your profile. -5. Accept the permissions to access your DiracX dashboard. - - πŸ’‘ You should be redirected to the DiracX-Web instance as a logged-in user, and the dashboard should appear. - -### Logging out - -1. Click on your profile icon in the top-right corner of the dashboard. - - :bulb: A dropdown menu should appear -2. Select **Logout** from the dropdown menu. - -## Advanced -### Logging in with specific properties - -TODO diff --git a/docs/user/web/monitor_jobs.md b/docs/user/web/monitor_jobs.md deleted file mode 100644 index 3d8b9b1f..00000000 --- a/docs/user/web/monitor_jobs.md +++ /dev/null @@ -1,36 +0,0 @@ -# Job Monitor documentation - -## The search bar - -The search bar allows you to filter jobs based on various criteria. The filters are represented as equations in the search bar, where each equation consists of a job attribute, an operator, and a value. A search is automatically performed when all the equations in the search bar are valid. - -### Create a filter -To create a filter, click on the search bar and start typing. Suggestions will appear based on the available job attributes. You can select a suggestion to choose the criterion. After that, you can either type or select an operator and a value to filter by. -The search bar only suggests attributes, operators, and values that are available in your current set of jobs. - -### Edit a filter -To edit a filter, click on the filter in the search bar. You can change the operator or value by clicking on them. You can also use the arrow keys to navigate through the equations and edit them. - -### Remove a filter -To remove a filter, you can either press the `Backspace` key to remove the last token or right-click on the equation to remove the entire equation. - - -## Use the table -By default, the jobs are displayed in a table. If you are viewing them in another chart, you can click the table button next to the search bar to switch back to the table view. -The table displays the jobs that match the criteria specified in the search bar. Each row represents a job, and the columns show various attributes of the job, such as its ID, status, type, and submission date. - -### Actions on the table -You can click on the eye icon to select more columns to display in the table. -You can sort the table by clicking on the column headers. Clicking on a column header will sort the table in ascending order, and clicking again will sort it in descending order. -You can set the page size by clicking on the `Row per page` dropdown at the bottom of the table. This allows you to control how many jobs are displayed per page. - -### Actions on a job -You can do a right-click on a job to open the `Job History`. -You can select one or more jobs by clicking on the checkboxes next to each job. Once you have selected jobs, you can perform actions on them using the buttons at the top of the table. The available actions include: -- **Get IDs**: This button will copy the IDs of the selected jobs to the clipboard. -- **Rechedule**: This button will reschedule the selected jobs. -- **Kill**: This button will kill the selected jobs. -- **Delete**: This button will delete the selected jobs. - -## Use the Pie Chart -You can change the visualization to use a pie chart with the button next to the search bar. The pie chart provides a hierarchical view of the jobs based on their attributes. The `Columns to plot` component lets you choose your criteria for visualizing the jobs. The chart can display two levels, and you can then click on a section of the chart to zoom into that category and see more details. diff --git a/packages/extensions/README.md b/packages/extensions/README.md index ccabfdb2..b62f1861 100644 --- a/packages/extensions/README.md +++ b/packages/extensions/README.md @@ -2,242 +2,4 @@ Extension Logo

-# Creating a DiracX Web Extension - -![CI](https://github.com/DIRACGrid/diracx-web/actions/workflows/gubbins-test.yml/badge.svg?branch=main) - This project aims to provide an example for creating a basic Next.js web extension for DiracX. It includes the necessary configuration and setup to get you started quickly. - -## Prerequisites - -Before starting, ensure you have the following installed: - -- [Docker](https://www.docker.com/get-started) -- [Node.js](https://nodejs.org/) -- [Git](https://git-scm.com/) - -And ensure you have basic knowledge of: - -- [React](https://react.dev/) -- [Next.js](https://nextjs.org/) -- [MUI](https://mui.com/) - -## Getting Started - -You can either create a new repository or start from this one to build your DiracX extension. Follow one of the methods below: - -### Method 1: Fork the Repository - -1. **Clone this repository** on GitHub, move and rename the `diracx-web/packages/extensions` directory: - - ```bash - git clone https://github.com/DIRACGrid/diracx-web.git - mv diracx-web/packages/extensions - cd - ``` - -2. **Slightly modify the `package.json` file** - - From ``, execute the following command: - - ```bash - # Adapt the path of the copy-service-worker-files script - jq '.scripts.postinstall = "node ./node_modules/@axa-fr/react-oidc/bin/copy-service-worker-files.mjs public"' ./package.json > ./package.temp.json - mv ./package.temp.json ./package.json - # Adapt the package name and version - jq '.name = ""' ./package.json > ./package.temp.json - mv ./package.temp.json ./package.json - jq '.version = "0.1.0-a0"' ./package.json > ./package.temp.json - mv ./package.temp.json ./package.json - ``` - -3. **Remove `CHANGELOG.md`** - -### Method 2: Create a New Next.js Project - -1. **Create a new Next.js project** using the following command: - - ```bash - npx create-next-app your-extension - cd your-extension - ``` - -2. **Add the DiracX Web Components Library** to your project: - - ```bash - npm install @dirac-grid/diracx-web-components - ``` - - To include additional dependencies in your project, such as `cypress` for end-to-end tests, you can follow these steps: - - Run the following command to install the desired dependency: - - ```bash - npm install - ``` - - Add the `--save-dev` or `-D` flag to install the dependency as a development dependency. - - Replace `` with the name of the dependency you want to install. - - For example, to install `cypress`, run: - - ```bash - npm install cypress -D - ``` - - Make sure to consult the documentation of each dependency for further instructions on how to use them in your project. - - For `cypress`, you can refer to the [Cypress documentation](https://docs.cypress.io/guides/overview/why-cypress.html) for detailed usage instructions. - -3. **Add the OIDC postinstall script** to your `package.json` file to copy necessary service worker files: - - ```json - "scripts": { - "postinstall": "node ./node_modules/@axa-fr/react-oidc/bin/copy-service-worker-files.mjs public" - } - ``` - - This is needed to update the service worker files when the OIDC library version changes. - - See the [OIDC library documentation](https://github.com/AxaFrance/oidc-client/tree/main/packages/react-oidc#getting-started) for more information. - - Note: for backendless local development, replace the `dev` command by: - - ```json - "scripts": { - "dev": "export NEXT_PUBLIC_DIRACX_URL=$DIRACX_URL; next dev", - ... - } - ``` - - This avoids having to set 2 environment variables with the same value: NextJS can only read from variables prefixed with `NEXT_PUBLIC`. - -4. **Edit the Next.js config** with these options: - - ```js - output: "export", - images: { - unoptimized: true, - }, - ``` - - The output is set to `export` to have a static application. - Images are left unoptimized because it's not well-supported with a static export. - -5. **Add the nginx config** located in the [`config/nginx`](config/nginx/) directory. - This adjustment ensures that Nginx can correctly handle requests for .html files and fall back appropriately, preventing the `404: Not Found` errors encountered when accessing routes like `/auth`. (see [#57](https://github.com/DIRACGrid/diracx-web/pull/57)) - -6. **Organize your pages** in the `src/app` app directory. - The `` context is needed by most of the components of `diracx-web-components`, so you should include it in the layouts of your application. Use `` to require authentication on a route. You can also override some default values of certain contexts like `` for the application list. - Finally, some components have some personalization options (i.e. the logo URL for the dashboard), check the [Storybook documentation](https://diracgrid.github.io/diracx-web/) to see the props of each component. - Check [the app directory](src/app/) in this example to have a reference. - -### Architecture - -We strongly recommend following the directory structure below to keep your project organized: - -- `/src/app`: Contains the main application logic and Next.js setup. This directory houses the core of the application built using Next.js, where each page.tsx file represents a page in the application with [folder-based routing](https://nextjs.org/docs/app/building-your-application/routing). [Next.js Official Documentation](https://nextjs.org/docs). - The page.tsx files contain the UI for a route and layout.tsx files handles the shared UI for a segment and its children. - In this example the `(Dashboard)` folder manages the main interface where users interact with the app's primary functions. Names in parentheses are ignored for the route, so it is the root URL. - The `auth` folder handles the authentication of users, and the route is `/auth`. - -- `/src/`: This directory includes the source code related to your extension. You can create custom components, hooks, ... in this directory. - - `/src//components`: Contains custom React components. This folder includes reusable UI components built using React. Components in React are independent, reusable pieces of UI that can manage their own state. [React Components](https://reactjs.org/docs/components-and-props.html) - - `/src//contexts`: Manages global state using React Context. This folder contains context providers which are used to manage and share global state across the application. React Context provides a way to pass data through the component tree without having to pass props down manually at every level. [React Context](https://reactjs.org/docs/context.html) - - `/src//hooks`: Custom React hooks for encapsulating reusable logic. This directory includes custom hooks. Hooks are special functions that let you "hook into" React state and lifecycle features from function components. [React Hooks](https://reactjs.org/docs/hooks-intro.html) - - `/src//types`: TypeScript type definitions for the application. This folder contains TypeScript type definitions to ensure type safety throughout the application. - -### Running the Extension with DiracX Charts - -To start your DiracX extension in development mode follow these steps: - -1. **Clone the `diracx-charts` repository** in a parent directory: - - ```bash - git clone git@github.com:DIRACGrid/diracx-charts.git - ``` - -2. **Run the demo script** with the path to your extension: - - ```bash - ./diracx-charts/run_demo.sh path/to/your-extension - ``` - -To run your extension in a production environment, you need to customize the [`diracx` Helm Chart](https://github.com/DIRACGrid/diracx-charts) values, such as: - -```yaml -global.images.web.tag: -global.images.web.repository: -``` - -## Customizing the Extension - -You can customize your extension by modifying the files in the `src` directory. This is where you’ll find the main components and logic of your extension. - -Having a directory dedicated to your extension components will help you keep your code organized and easy to maintain. - -### Extending the DiracX Apps - -To add new apps to your extension, you can create new components in your extension directory. - -[`testApp`](src/gubbins/components/TestApp/testApp.tsx) provides an example of a basic app component and the [Storybook documentation](https://diracgrid.github.io/diracx-web/) showcases all the components you can use from the library in an interactive interface. - -It is then pretty easy to add them to DiracX Web by extending the `applicationList` (the list of apps available in DiracX-Web) from `diracx-web-components/components`. - -Context providers are used to manage and share global state across the application. You can use the `ApplicationProvider` from `diracx-web-components/contexts` to pass the list of applications to the components that need it. -It is used in this example in the [(Dashboard) directory's layout.tsx]() file. - -If you need more info on Contexts, you can check the [React documentation](https://reactjs.org/docs/context.html). - -```tsx -// import the Application Context Provider and the default application list from the library -import { ApplicationProvider } from "@dirac-grid/diracx-web-components/contexts"; -import { applicationList } from "@dirac-grid/diracx-web-components/components"; - -// The new Application you want to add -const newApp = { - name: "New App", // Its name - icon: new-app-icon, // An icon for the app, you can import some from "@mui/icons-material" - component: NewAppComponent, // The component you made for your Application -}; - -// Make a new list with all elements of the default list + the new application -const newApplicationList = [...applicationList, newApp]; - -// Use your new list by passing in the Application provider in a page's layout -...; -``` - -In this example, the new App list is defined in a [separate file](src/gubbins/applicationList.ts) - -Feel free to explore and adjust the code to fit your requirements. - -## Deployment - -Deployment of the extension can be done using the Dockerfile provided in the repository. The Dockerfile builds the Next.js application and serves it using a nginx server. - -See [Docker's Documentation](https://docs.docker.com/get-started/) for more information on how to deploy your application using Docker. -It can be automatically deployed using CI/CD tools like GitHub Actions, GitLab CI/CD, or Jenkins. - -## Good Practices - -- **Code Quality**: Ensure your code is clean, well-documented, and follows best practices. Use tools like [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/) to maintain code quality. - -- **Testing**: - - **Component Testing**: Write tests for your components to ensure they work as expected. Use [Jest](https://jestjs.io/) for unit testing and snapshot testing of your React components. - - **Application Testing**: Use [Cypress](https://www.cypress.io/) for end-to-end testing to simulate real user interactions and ensure your application behaves correctly. - - **Test Coverage**: Maintain good test coverage to ensure that your critical features are well-protected during updates. Tools like Jest provide [coverage reports](https://jestjs.io/docs/code-coverage) that help you identify untested parts of your code. - -- **Accessibility**: Make your extension accessible to all users. Use semantic HTML, ARIA attributes, and test your extension with different screen sizes and assistive technologies. - -- **Security**: - - **Dependency Management**: Keeping dependencies up to date is crucial for security and performance. Using deprecated packages can expose your application to known vulnerabilities. - - **Identifying Vulnerabilities**: Regularly check for known vulnerabilities in your dependencies. Tools like [`npm audit`](https://docs.npmjs.com/cli/v7/commands/npm-audit) can help spot these issues. - - **Automating Updates**: Use tools like [Dependabot](https://github.com/dependabot) or [Renovate](https://www.whitesourcesoftware.com/free-developer-tools/renovate/) to automate dependency updates. These tools can automatically create pull requests to update dependencies, making it easier to stay current and see if updates are compatible with tests used in CI. Keeping dependencies up to date is crucial for security as deprecated packages can expose your application to known vulnerabilities. - -By following these practices, you'll ensure that your codebase remains robust, secure, and maintainable. - -## License - -This project is licensed under the GNU General Public License v3.0 (GPL-3.0). Please refer to the [LICENSE](LICENSE) file for more details.