diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 54d11e31..f8e1f3bd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,4 +14,4 @@ Thank you for your interest in contributing to our project! We appreciate all co - Create a [:bust_in_silhouette: User Story](https://github.com/DIRACGrid/diracx-web/discussions/categories/user-personas-and-stories) to describe your need and share your design ideas if any. - **Want to contribute to the :computer: codebase?** - - Read the [:book: Developer Guide](docs/developer/index.md) to set up your environment and get started. + - Read the [:book: Developer Guide](docs/dev/how-to/contribute.md) to set up your environment and get started. diff --git a/docs/admin/deploy_instance.md b/docs/admin/deploy_instance.md deleted file mode 100644 index a6334f6d..00000000 --- a/docs/admin/deploy_instance.md +++ /dev/null @@ -1,43 +0,0 @@ -# Deploying the web interface -## DiracX-Web - -### 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. - -### Production mode - -To deploy `diracx-web` in a production environment, you need to customize the [`diracx` Helm Chart](https://github.com/DIRACGrid/diracx-charts) values. Key parameters include: - -```yaml -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. - -### Integrating new features/hotfixes - -To hotfix `diracx-web`, test new features, you can provide a specific PR within [`diracx` Helm Chart](https://github.com/DIRACGrid/diracx-charts) values, such as: - -```yaml -diracxWeb.repoURL: -diracxWeb.branch: -``` - -:bulb: 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). - -### `gubbins` extension in development mode, as a standalone - -By default, the `gubbins` extension is part of a monorepo and uses a local version of `diracx-web-components`. This setup is not representative of a standalone extension configuration. - -To deploy gubbins as a standalone package: -- **Isolate the `packages/extensions` directory:** Copy the content of `packages/extensions` to a new repository or directory outside the monorepo. -- **Update Configuration:** Adjust relevant variables to align with a standalone setup. Review the gubbins-test GitHub Action workflow for required changes. diff --git a/docs/admin/how-to/deploy_instance.md b/docs/admin/how-to/deploy_instance.md new file mode 100644 index 00000000..ccca761d --- /dev/null +++ b/docs/admin/how-to/deploy_instance.md @@ -0,0 +1,56 @@ +# Deploying the web interface +## DiracX-Web + +### Development mode + +Refer to the [Developer Guide: Getting Started](../../dev/tutorials/getting_started.md) for instructions on running `diracx-web` in development mode. + +### Production mode + +To deploy `diracx-web` in a production environment, you need to customize the [`diracx` Helm Chart](https://github.com/DIRACGrid/diracx-charts) values. Key parameters include: + +```yaml title="Helm Chart values for production deployment" +global.images.web.tag: +global.images.web.repository: +``` + +!!! tip "Version Configuration" + Make sure to update these values to point to the appropriate Docker image and version for your deployment. + +### Integrating new features/hotfixes + +=== "Testing Features" + + To hotfix `diracx-web` or test new features, you can provide a specific PR within [`diracx` Helm Chart](https://github.com/DIRACGrid/diracx-charts) values, such as: + + ```yaml title="Helm Chart values for feature testing" + diracxWeb.repoURL: + diracxWeb.branch: + ``` + +=== "Production Hotfixes" + + For urgent production hotfixes: + + 1. Create a hotfix branch from the production release + 2. Apply the minimal fix required + 3. Test thoroughly in a staging environment + 4. Update the Helm Chart values to point to the hotfix image + +!!! warning "Deployment Safety" + Always test changes in a staging environment before applying to production. + +## Extension + + +### `gubbins` extension in development mode + +For managing the `gubbins` extension in development mode, refer to the [Developer Guide: Managing an extension](../../dev/how-to/manage_extension.md). + +### `gubbins` extension in development mode, as a standalone + +By default, the `gubbins` extension is part of a monorepo and uses a local version of `diracx-web-components`. This setup is not representative of a standalone extension configuration. + +To deploy gubbins as a standalone package: +- **Isolate the `packages/extensions` directory:** Copy the content of `packages/extensions` to a new repository or directory outside the monorepo. +- **Update Configuration:** Adjust relevant variables to align with a standalone setup. Review the gubbins-test GitHub Action workflow for required changes. diff --git a/docs/admin/how-to/index.md b/docs/admin/how-to/index.md index e69de29b..fbfe3d21 100644 --- a/docs/admin/how-to/index.md +++ b/docs/admin/how-to/index.md @@ -0,0 +1,32 @@ +# Administrator How-To Guides + +This section provides guides for administrators managing DiracX Web deployments and infrastructure. + +## Available Guides + +!!! info "Deployment Guide" + Start with the [Deployment Guide](../deploy_instance.md) for setting up DiracX Web in production. + +=== "Deployment & Operations" + + **[Deploy Instance](../deploy_instance.md)** + : Complete guide for deploying DiracX Web in production environments. + +=== "Maintenance" + + **[Manage Dependencies](../manage_dependencies.md)** + : Learn how to handle dependency updates and security vulnerabilities. + + **[Manage Releases](../manage_release.md)** + : Guide for managing DiracX Web releases and versioning. + +## Best Practices + +!!! tip "Production Checklist" + - Always test in staging before deploying to production + - Monitor application performance and logs + - Keep dependencies updated for security + - Maintain proper backup procedures + +!!! warning "Security Considerations" + Regularly review and apply security updates. Enable automated security alerts in your GitHub repository settings. \ No newline at end of file diff --git a/docs/admin/how-to/manage_dependencies.md b/docs/admin/how-to/manage_dependencies.md new file mode 100644 index 00000000..f44e3224 --- /dev/null +++ b/docs/admin/how-to/manage_dependencies.md @@ -0,0 +1,73 @@ +# Managing web 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. + +!!! info "Weekly Schedule" + In the `diracx-web` repository, Dependabot is configured to run weekly, generating PRs for any outdated or vulnerable dependencies. + +=== "Review 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. + +=== "Verify Tests" + + **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. + +=== "Adapt Code" + + **Local Development** + : ```bash title="Working with Dependabot branches" + # Check out the PR branch locally + git checkout dependabot/branch-name + + # Run tests locally + npm test + + # Make necessary fixes + # ... edit code ... + + # Test your changes + npm run test:diracx-web-components + npm run --prefix packages/diracx-web test + ``` + + **Implement Fixes** + : Modify the codebase to address any issues introduced by the dependency update. + +=== "Merge & Monitor" + + **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. + + !!! warning "Deployment Monitoring" + Keep a close eye on the application after dependency updates to catch any unexpected issues early. + +## 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. + +!!! danger "Security Alert Process" + Navigate to the repository's **"Security"** tab and select **"Dependabot alerts"** to view any security vulnerabilities identified in the dependencies. + + **Priority Levels:** + + - **Critical**: Immediate action required + - **High**: Address within 1 week + - **Medium**: Address within 1 month + - **Low**: Address during next maintenance cycle + +!!! tip "Proactive Security" + Enable GitHub's security alerts and automatic security updates for immediate notification of vulnerabilities in your dependencies. diff --git a/docs/admin/manage_release.md b/docs/admin/how-to/manage_release.md similarity index 97% rename from docs/admin/manage_release.md rename to docs/admin/how-to/manage_release.md index 614d5b3a..e5e7d39d 100644 --- a/docs/admin/manage_release.md +++ b/docs/admin/how-to/manage_release.md @@ -1,4 +1,4 @@ -# Release Management +# Managing web releases ```mermaid sequenceDiagram 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/web-arch.md b/docs/dev/explanations/web-arch.md similarity index 50% rename from docs/dev/web-arch.md rename to docs/dev/explanations/web-arch.md index 337d17ef..645264c4 100644 --- a/docs/dev/web-arch.md +++ b/docs/dev/explanations/web-arch.md @@ -1,10 +1,4 @@ - -# 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 +# Web architecture Overview ```mermaid --- @@ -38,17 +32,23 @@ flowchart TD 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-Components" -- [**DiracX-Web**](packages/diracx-web): Vanilla Dirac web interface based on Next.js. Leverages components from `DiracX-Web-Components` to provide core functionalities. + **Purpose**: A library of reusable React components + **Location**: `packages/diracx-web-components` + **Description**: Designed for integration within the `DiracX-Web` package and to facilitate the creation of custom DiracX web extensions. -- [**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. +=== "DiracX-Web" + **Purpose**: Main web application + **Location**: `packages/diracx-web` + **Description**: Vanilla Dirac web interface based on Next.js. Leverages components from `DiracX-Web-Components` to provide core functionalities. -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. +=== "Extensions" -## Ramping up + **Purpose**: Example extension implementation + **Location**: `packages/extensions` + **Description**: 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. -- [Set up a development environment](setup_environment.md) -- [Manage the extension](manage_extension.md) -- [Contribute to the effort](../developer/contribute.md) +!!! info "Monorepo Structure" + 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. \ No newline at end of file diff --git a/docs/dev/how-to/contribute.md b/docs/dev/how-to/contribute.md new file mode 100644 index 00000000..c89d44b0 --- /dev/null +++ b/docs/dev/how-to/contribute.md @@ -0,0 +1,82 @@ +# Contributing to DiracX-Web + +### 1. Open an Issue + +!!! tip "Discussion First" + 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. + +!!! info "Check 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. + +!!! success "Good First Issues" + 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 are well-suited for newcomers to the project. + +### 2. Make Changes + +!!! info "Requirements" + [Getting Started](../tutorials/getting_started.md) + +=== "Repository Setup" + + **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. + +=== "Documentation" + + **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" + + **Inclusive Design** + : Make your application accessible to all users. Use semantic HTML, ARIA attributes, and test your application with different screen sizes and assistive technologies. + +!!! tip "Component Exports" + 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 "Breaking Changes" + 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 + +!!! info "Conventional Commits Required" + 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 +``` + +!!! danger "CI Requirement" + 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 "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. + + +### 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/dev/how-to/index.md b/docs/dev/how-to/index.md index e69de29b..fee5bfe0 100644 --- a/docs/dev/how-to/index.md +++ b/docs/dev/how-to/index.md @@ -0,0 +1,28 @@ +# Developer How-To Guides + +This section contains step-by-step guides for common development tasks with DiracX Web. + +## Available Guides + +!!! info "Getting Started" + New to DiracX Web development? Start with [Getting Started](../tutorials/getting_started.md). + +=== "Development Setup" + + **[Getting Started](../tutorials/getting_started.md)** + : Complete tutorial to set up your development environment and understand the DiracX Web project structure. + +=== "Application Development" + + **[Create Application](./create_application.md)** + : Learn how to create new applications within the DiracX Web ecosystem. + +=== "Extension Development" + + **[Manage Extension](./manage_extension.md)** + : Guide for working with and creating DiracX Web extensions. + +## Development Resources + +- [Web Architecture Overview](../web-arch.md) +- [Contributing Guidelines](../dev/contribute.md) \ No newline at end of file diff --git a/docs/dev/how-to/manage_extension.md b/docs/dev/how-to/manage_extension.md new file mode 100644 index 00000000..f5a0f32c --- /dev/null +++ b/docs/dev/how-to/manage_extension.md @@ -0,0 +1,240 @@ +# 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. + +### Modifying the `gubbins` extension + +This implies setting up the backend as well as the frontend. + +#### `gubbins-web` (frontend) + +```mermaid +--- +config: + layout: elk +--- +flowchart TD + subgraph root-cmds["root package.json"] + root:dev["dev"] + end + subgraph gubbins-cmds["extensions[gubbins] package.json"] + nextdev["next dev"] + gubbins:dev["dev"] + cypress["cypress"] + gubbins:test["test"] + next["next build"] + gubbins:build["build"] + end + subgraph ext["extensions[gubbins]"] + diracx-src["/src"] + diracx-out["/out"] + end + subgraph lib["diracx-web-components"] + lib-src["/src"] + lib-out["/dist"] + end + user["Developer"] --> root-cmds + gubbins:dev -.-> nextdev + gubbins:test -.-> cypress + gubbins:build -.-> next + root:dev -- calls --> gubbins:dev + root:dev ----x diracx-web-cmds["diracx-web package.json"] + cypress -- uses --> diracx-src + nextdev -- uses --> diracx-src + next -- builds --> diracx-out + next -. needs .-> lib-out + root:dev:::Ash + nextdev:::Rose + gubbins:dev:::Ash + cypress:::Rose + gubbins:test:::Ash + next:::Rose + gubbins:build:::Ash + diracx-src:::Peach + diracx-out:::Peach + lib-src:::Peach + lib-out:::Peach + classDef Ash stroke-width:1px, stroke-dasharray:none, stroke:#999999, fill:#EEEEEE, color:#000000 + classDef Peach stroke-width:1px, stroke-dasharray:none, stroke:#FBB35A, fill:#FFEFDB, color:#8F632D + classDef Rose stroke-width:1px, stroke-dasharray:none, stroke:#FF5978, fill:#FFDFE5, color:#8E2236 + style user stroke:#000000 + style root-cmds fill:#FFFFFF,stroke:#424242,color:#000000 + style diracx-web-cmds fill:#FFFFFF,stroke:#424242,color:#000000 + style gubbins-cmds fill:#FFFFFF,stroke:#424242,color:#000000 + style lib fill:#d99fe3,stroke:#FFCDD2,color:#000000 + style ext fill:#d99fe3,stroke:#FFCDD2,color:#000000 +``` + +You can simply, and temporarily modify `package.json` by replacing the `dev` command such as: + +```bash +jq '.scripts.dev["@dirac-grid/diracx-web-components"] = "npm --prefix packages/extensions run dev"' diracx-web/package.json > diracx-web/package.temp.json +mv diracx-web/package.temp.json diracx-web/package.json +``` + +And you would provide the `./diracx-web` directory to `diracx-charts/run_demo.sh` as usual: + +```bash +# Run the demo +diracx-charts/run_demo.sh ./diracx-web ...[backend params] + +# We use the test command from packages/extensions though +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). + +!!! tip "Automatic Updates" + 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`. + +### 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 + +### Using the gubbins extension as a template + +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. + +!!! info "Extension Guide" + More details are available in the [**extensions** README](../../packages/extensions/README.md) + +## 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/dev/manage_extension.md b/docs/dev/manage_extension.md deleted file mode 100644 index be82b526..00000000 --- a/docs/dev/manage_extension.md +++ /dev/null @@ -1,92 +0,0 @@ -# Dealing with an extension - -## Modifying the `gubbins` extension - -This implies setting up the backend as well as the frontend. - -### `gubbins-web` (frontend) - -```mermaid ---- -config: - layout: elk ---- -flowchart TD - subgraph root-cmds["root package.json"] - root:dev["dev"] - end - subgraph gubbins-cmds["extensions[gubbins] package.json"] - nextdev["next dev"] - gubbins:dev["dev"] - cypress["cypress"] - gubbins:test["test"] - next["next build"] - gubbins:build["build"] - end - subgraph ext["extensions[gubbins]"] - diracx-src["/src"] - diracx-out["/out"] - end - subgraph lib["diracx-web-components"] - lib-src["/src"] - lib-out["/dist"] - end - user["Developer"] --> root-cmds - gubbins:dev -.-> nextdev - gubbins:test -.-> cypress - gubbins:build -.-> next - root:dev -- calls --> gubbins:dev - root:dev ----x diracx-web-cmds["diracx-web package.json"] - cypress -- uses --> diracx-src - nextdev -- uses --> diracx-src - next -- builds --> diracx-out - next -. needs .-> lib-out - root:dev:::Ash - nextdev:::Rose - gubbins:dev:::Ash - cypress:::Rose - gubbins:test:::Ash - next:::Rose - gubbins:build:::Ash - diracx-src:::Peach - diracx-out:::Peach - lib-src:::Peach - lib-out:::Peach - classDef Ash stroke-width:1px, stroke-dasharray:none, stroke:#999999, fill:#EEEEEE, color:#000000 - classDef Peach stroke-width:1px, stroke-dasharray:none, stroke:#FBB35A, fill:#FFEFDB, color:#8F632D - classDef Rose stroke-width:1px, stroke-dasharray:none, stroke:#FF5978, fill:#FFDFE5, color:#8E2236 - style user stroke:#000000 - style root-cmds fill:#FFFFFF,stroke:#424242,color:#000000 - style diracx-web-cmds fill:#FFFFFF,stroke:#424242,color:#000000 - style gubbins-cmds fill:#FFFFFF,stroke:#424242,color:#000000 - style lib fill:#d99fe3,stroke:#FFCDD2,color:#000000 - style ext fill:#d99fe3,stroke:#FFCDD2,color:#000000 -``` - -You can simply, and temporarily modify `package.json` by replacing the `dev` command such as: - -```bash -jq '.scripts.dev["@dirac-grid/diracx-web-components"] = "npm --prefix packages/extensions run dev"' diracx-web/package.json > diracx-web/package.temp.json -mv diracx-web/package.temp.json diracx-web/package.json -``` - -And you would provide the `./diracx-web` directory to `diracx-charts/run_demo.sh` as usual: - -```bash -# Run the demo -diracx-charts/run_demo.sh ./diracx-web ...[backend params] - -# We use the test command from packages/extensions though -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 diff --git a/docs/dev/setup_environment.md b/docs/dev/setup_environment.md deleted file mode 100644 index 22302cf0..00000000 --- a/docs/dev/setup_environment.md +++ /dev/null @@ -1,171 +0,0 @@ -# Setting up your Development Environment - -```mermaid ---- -config: - layout: elk ---- -flowchart TD - subgraph root-cmds["root package.json"] - root:dev["dev"] - root:test["test"] - root:build["build"] - root:test:lib["test:diracx-web-components"] - root:build:lib["build:diracx-web-components"] - root:doc:lib["doc:diracx-web-components"] - end - subgraph lib-cmds["diracx-web-components package.json"] - tsup:watch["tsup --watch"] - lib:dev["dev"] - jest["jest"] - lib:test["test"] - tsup:build["tsup"] - lib:build["build"] - storybook["storybook dev"] - lib:storybook["doc"] - end - subgraph diracx-web-cmds["diracx-web package.json"] - nextdev["next dev"] - diracx-web:dev["dev"] - cypress["cypress"] - diracx-web:test["test"] - next["next build"] - diracx-web:build["build"] - end - subgraph diracx-web["diracx-web"] - diracx-src["/src"] - diracx-out["/out"] - end - subgraph lib["diracx-web-components"] - lib-src["/src"] - lib-out["/dist"] - end - lib:dev --> tsup:watch - lib:test --> jest - lib:build --> tsup:build - lib:storybook --> storybook - diracx-web:dev -.-> nextdev - diracx-web:test -.-> cypress - diracx-web:build -.-> next - user["Developer"] --> root-cmds - root:test:lib -- calls --> lib:test - root:build:lib -- calls --> lib:build - root:doc:lib -- calls --> lib:storybook - root:dev -- calls --> diracx-web:dev - root:build -- calls --> diracx-web:build - root:test -- calls --> diracx-web:test - root:test ~~~ gubbins-cmds["**extensions[gubbins] package.json**"] - cypress -- uses --> diracx-src - nextdev -- uses --> diracx-src - nextdev -. watches(next config) .-> lib-src - next -- builds --> diracx-out - next -. needs .-> lib-out - tsup:watch -- builds --> lib-out - tsup:watch -. watches .-> lib-src - jest -- uses --> lib-src - tsup:build -- builds --> lib-src - storybook -- uses --> lib-src - root:dev:::Ash - root:test:::Ash - root:build:::Ash - root:test:lib:::Ash - root:build:lib:::Ash - root:doc:lib:::Ash - tsup:watch:::Rose - lib:dev:::Ash - jest:::Rose - lib:test:::Ash - tsup:build:::Rose - lib:build:::Ash - storybook:::Rose - lib:storybook:::Ash - nextdev:::Rose - diracx-web:dev:::Ash - cypress:::Rose - diracx-web:test:::Ash - next:::Rose - diracx-web:build:::Ash - diracx-src:::Peach - diracx-out:::Peach - lib-src:::Peach - lib-out:::Peach - classDef Ash stroke-width:1px, stroke-dasharray:none, stroke:#999999, fill:#EEEEEE, color:#000000 - classDef Peach stroke-width:1px, stroke-dasharray:none, stroke:#FBB35A, fill:#FFEFDB, color:#8F632D - classDef Rose stroke-width:1px, stroke-dasharray:none, stroke:#FF5978, fill:#FFDFE5, color:#8E2236 - style user stroke:#000000 - style lib fill:#d99fe3,stroke:#FFCDD2,color:#000000 - style diracx-web fill:#d99fe3,stroke:#FFCDD2,color:#000000 -``` - -## Running DiracX-Web in development mode - -_Requirements: node, npm_ - -You can start `DiracX-Web` as an `npm` application connecting to a remote backend server - code changes will be reflected in the demo in real time. - -```bash -# Clone the diracx-web repository -git clone git@github.com:DIRACGrid/diracx-web.git - -cd diracx-web - -# Install it -npm ci - -# Set the DiracX backend URL you are targeting -export NEXT_PUBLIC_DIRACX_URL= - -# Run it -npm run dev -``` - -## Running DiracX-Web in development mode along DiracX - -_Requirements: docker, internet, node_ - -If you need to modify `DiracX` in parallel, or if you do not have access to the remote backend logs, -then you can also start the full demo setup in development mode: - -```bash -# Clone the diracx-web repository -git clone git@github.com:DIRACGrid/diracx-web.git - -# [Optional] Clone the diracx repository -git clone git@github.com:DIRACGrid/diracx.git - -# Clone the diracx-chart repository -git clone git@github.com:DIRACGrid/diracx-charts.git - -# Run the demo -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. - -## Testing - -[Jest](https://jestjs.io/) unit tests can be started with: - -```bash -npm run test:diracx-web-components -``` - -End-to-end tests are launched through [Cypress](https://www.cypress.io/) such as: - -```bash -# diracx-charts/run_demo.sh is running -export DIRACX_URL= -npm run --prefix packages/diracx-web test -``` - -## Documenting - -[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/tutorials/getting_started.md b/docs/dev/tutorials/getting_started.md new file mode 100644 index 00000000..3a130a58 --- /dev/null +++ b/docs/dev/tutorials/getting_started.md @@ -0,0 +1,262 @@ +# Getting Started with DiracX-Web Development + +Welcome to DiracX-Web development! This tutorial will guide you through setting up your development environment and getting your first local instance running. By the end of this guide, you'll have a working development setup and understand the project architecture. + +```mermaid +--- +config: + layout: elk +--- +flowchart TD + subgraph root-cmds["root package.json"] + root:dev["dev"] + root:test["test"] + root:build["build"] + root:test:lib["test:diracx-web-components"] + root:build:lib["build:diracx-web-components"] + root:doc:lib["doc:diracx-web-components"] + end + subgraph lib-cmds["diracx-web-components package.json"] + tsup:watch["tsup --watch"] + lib:dev["dev"] + jest["jest"] + lib:test["test"] + tsup:build["tsup"] + lib:build["build"] + storybook["storybook dev"] + lib:storybook["doc"] + end + subgraph diracx-web-cmds["diracx-web package.json"] + nextdev["next dev"] + diracx-web:dev["dev"] + cypress["cypress"] + diracx-web:test["test"] + next["next build"] + diracx-web:build["build"] + end + subgraph diracx-web["diracx-web"] + diracx-src["/src"] + diracx-out["/out"] + end + subgraph lib["diracx-web-components"] + lib-src["/src"] + lib-out["/dist"] + end + lib:dev --> tsup:watch + lib:test --> jest + lib:build --> tsup:build + lib:storybook --> storybook + diracx-web:dev -.-> nextdev + diracx-web:test -.-> cypress + diracx-web:build -.-> next + user["Developer"] --> root-cmds + root:test:lib -- calls --> lib:test + root:build:lib -- calls --> lib:build + root:doc:lib -- calls --> lib:storybook + root:dev -- calls --> diracx-web:dev + root:build -- calls --> diracx-web:build + root:test -- calls --> diracx-web:test + root:test ~~~ gubbins-cmds["**extensions[gubbins] package.json**"] + cypress -- uses --> diracx-src + nextdev -- uses --> diracx-src + nextdev -. watches(next config) .-> lib-src + next -- builds --> diracx-out + next -. needs .-> lib-out + tsup:watch -- builds --> lib-out + tsup:watch -. watches .-> lib-src + jest -- uses --> lib-src + tsup:build -- builds --> lib-src + storybook -- uses --> lib-src + root:dev:::Ash + root:test:::Ash + root:build:::Ash + root:test:lib:::Ash + root:build:lib:::Ash + root:doc:lib:::Ash + tsup:watch:::Rose + lib:dev:::Ash + jest:::Rose + lib:test:::Ash + tsup:build:::Rose + lib:build:::Ash + storybook:::Rose + lib:storybook:::Ash + nextdev:::Rose + diracx-web:dev:::Ash + cypress:::Rose + diracx-web:test:::Ash + next:::Rose + diracx-web:build:::Ash + diracx-src:::Peach + diracx-out:::Peach + lib-src:::Peach + lib-out:::Peach + classDef Ash stroke-width:1px, stroke-dasharray:none, stroke:#999999, fill:#EEEEEE, color:#000000 + classDef Peach stroke-width:1px, stroke-dasharray:none, stroke:#FBB35A, fill:#FFEFDB, color:#8F632D + classDef Rose stroke-width:1px, stroke-dasharray:none, stroke:#FF5978, fill:#FFDFE5, color:#8E2236 + style user stroke:#000000 + style lib fill:#d99fe3,stroke:#FFCDD2,color:#000000 + style diracx-web fill:#d99fe3,stroke:#FFCDD2,color:#000000 +``` + +## What You'll Learn + +In this tutorial, you'll learn how to: + +- Set up your development environment +- Understand the DiracX-Web project structure +- Run the application locally +- Make your first changes with hot reload +- Run tests and documentation tools + +## Prerequisites + +Before we begin, make sure you have the following installed on your system: + +- **Node.js** (version 18 or higher) - [Download here](https://nodejs.org/) +- **npm** (comes with Node.js) +- **Git** - [Download here](https://git-scm.com/) + +## Step 1: Clone and Set Up the Project + +Let's start by getting the DiracX-Web code on your machine and installing dependencies. + +```bash title="Clone and install dependencies" +# 1. Clone the repository +git clone git@github.com:DIRACGrid/diracx-web.git + +# 2. Navigate to the project directory +cd diracx-web + +# 3. Install all dependencies (this may take a few minutes) +npm ci +``` + +🎉 Great! You now have all the project dependencies installed. + +## Step 2: Understanding the Project Structure + +Before running the application, let's understand what you just downloaded. DiracX-Web is a monorepo with three main parts: + +``` +diracx-web/ +├── packages/ +│ ├── diracx-web-components/ # 📦 Reusable React components library +│ ├── diracx-web/ # 🌐 Main Next.js web application +│ └── extensions/ # 🔌 Example extensions +├── docs/ # 📚 Documentation (you're reading this!) +└── package.json # 🛠️ Root package configuration +``` + +The architecture diagram above shows how these pieces work together during development. + +## Step 3: Run Your First Development Server + +Now let's get the application running locally. You have two options: + +### Option A: Connect to a Remote Backend (Recommended for Beginners) + +This is the easiest way to get started - you'll run the frontend locally but connect to an existing DiracX backend: + +```bash title="Run with remote backend" +# Set the backend URL (replace with actual backend) +export NEXT_PUBLIC_DIRACX_URL= + +# Start the development server +npm run dev +``` + +Once you run this command, open your browser to `http://localhost:3000` and you should see the DiracX-Web interface! 🚀 + +### Option B: Full Local Development (Advanced) + +If you want to run both the frontend and backend locally, or need to modify DiracX backend code: + +!!! info "Additional Requirements for Option B" + - Docker + - Internet connection + +```bash title="Running full development environment" +# 1. Clone additional repositories +git clone git@github.com:DIRACGrid/diracx.git # Backend code (optional) +git clone git@github.com:DIRACGrid/diracx-charts.git # Deployment scripts + +# 2. Run the full demo environment +diracx-charts/run_demo.sh ./diracx-web [./diracx] +``` + +!!! tip "Hot Reload Magic" + Any changes you make to the `diracx-web-components` library are automatically reflected in your running application. This is powered by NextJS's transpile feature - no manual rebuilds needed! + +## Step 4: Explore the Development Tools + +Now that you have the application running, let's explore the development tools available: + +### Component Documentation with Storybook + +DiracX-Web uses [Storybook](https://storybook.js.org/) to document and showcase the component library: + +```bash title="View component documentation" +npm run doc:diracx-web-components +``` + +This opens Storybook at `http://localhost:6006` where you can: +- Browse all available components +- See live examples and documentation +- Test component variations interactively + +### Running Tests + +DiracX-Web has comprehensive testing coverage: + +```bash title="Run component unit tests" +# Test the component library +npm run test:diracx-web-components +``` + +For end-to-end testing (requires a running backend): + +```bash title="Run E2E tests" +# Make sure your development server or demo is running first +export DIRACX_URL= +npm run --prefix packages/diracx-web test +``` + +### Code Quality Tools + +Keep your code clean with the built-in linting and formatting: + +```bash title="Check code quality" +# Lint all code +npm run lint + +# TypeScript type checking +npm run ts-lint +``` + +## Step 5: Make Your First Change + +Let's make a simple change to verify everything is working: + +1. **Find a component** - Open `packages/diracx-web-components/src/components/` +2. **Make a small change** - Edit any component file (try changing some text) +3. **See it live** - Your browser should automatically refresh and show the change! + +## What's Next? + +Congratulations! 🎉 You now have a working DiracX-Web development environment. Here's what you can explore next: + +- **📖 Read the [Contributing Guidelines](contribute.md)** - Learn the development workflow and coding standards +- **🔧 Explore the [Extension Management Guide](manage_extension.md)** - Learn how to create and manage extensions +- **📚 Browse the [Project Architecture](../explanations/web-arch.md)** - Understand the technical decisions behind DiracX-Web +- **🏗️ Check the component library** - Run Storybook and explore available components + +## Getting Help + +If you run into issues: + +1. **Check existing [GitHub Issues](https://github.com/DIRACGrid/diracx-web/issues)** +2. **Start a [Discussion](https://github.com/DIRACGrid/diracx-web/discussions)** for questions +3. **Review the [Contributing Guidelines](contribute.md)** for development practices + +Happy coding! 🚀 \ No newline at end of file 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..64d0ba3e 100644 --- a/docs/user/how-to/index.md +++ b/docs/user/how-to/index.md @@ -0,0 +1,33 @@ +# DiracX Web User Guide + +Welcome to the DiracX Web interface! This section provides comprehensive guides for using the DiracX web application. + +## Getting Started + +!!! info "First Time Users" + If this is your first time using DiracX Web, start with the [login guide](login_out.md) to learn how to access the system. + +## Available Guides + +=== "Authentication" + + **[Logging in & out](login_out.md)** + : Learn how to authenticate with DiracX Web and manage your session. + +=== "Job Management" + + **[Monitor Jobs](monitor_jobs.md)** + : Comprehensive guide to job monitoring, filtering, and management using the web interface. + +=== "Application Management" + + **[List and Share Applications](list_and_share_applications.md)** + : Learn how to view and share your applications within the DiracX ecosystem. + +## Quick Tips + +!!! tip "Browser Requirements" + DiracX Web works best with modern browsers (Chrome, Firefox, Safari, Edge). Make sure JavaScript is enabled. + +!!! warning "Session Management" + Your session will expire after a period of inactivity. Save your work regularly and log back in when prompted. diff --git a/docs/user/web/list_and_share_applications.md b/docs/user/how-to/list_and_share_applications.md similarity index 100% rename from docs/user/web/list_and_share_applications.md rename to docs/user/how-to/list_and_share_applications.md diff --git a/docs/user/web/login_out.md b/docs/user/how-to/login_out.md similarity index 61% rename from docs/user/web/login_out.md rename to docs/user/how-to/login_out.md index 1c8fab94..1e9f900e 100644 --- a/docs/user/web/login_out.md +++ b/docs/user/how-to/login_out.md @@ -5,21 +5,26 @@ ### Logging in 1. Go to the DiracX-Web instance homepage. - - 💡 You should end up on an authentication page. + !!! note + 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. + !!! note + 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. + !!! note + 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. + !!! success + 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 + !!! note + A dropdown menu should appear 2. Select **Logout** from the dropdown menu. ## Advanced diff --git a/docs/user/how-to/monitor_jobs.md b/docs/user/how-to/monitor_jobs.md new file mode 100644 index 00000000..c1a2c10d --- /dev/null +++ b/docs/user/how-to/monitor_jobs.md @@ -0,0 +1,65 @@ +# 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 :material-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/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.