Skip to content

developers_guide.md

Latest commit

 

History

History
160 lines (101 loc) · 7.02 KB

developers_guide.md

File metadata and controls

160 lines (101 loc) · 7.02 KB

EBRAINS Model Catalog app: Guide for Developers and Maintainers

The Model Catalog app is a web-browser-based graphical user interface for the EBRAINS Model Validation Framework.

This document is intended for developers and maintainers of the app.

The app source code is available on Github. The repository also contains the source code for the Model Validation Service API, and for the Curation Dashboard app. In what follows, the "root directory of the app" means the directory apps/model_catalog within the Github project.

Architecture

The app is based on Create React App, using Material-UI for layout and styling.

It is a single-page app, using modal dialogs to display different views. The app may be embedded in the EBRAINS Collaboratory as a "community app", in which case it communicates with the Collaboratory to store per-user settings.

Authentication / authorization uses EBRAINS IAM. Access to private models is based on collab membership.

Setting up a development environment

If you haven't already forked the Github project, then do so and git clone your fork.

In the root directory of the app run

$ npm install

To run the app in development mode

$ npm start

Open http://localhost:3000 to view it in the browser.

Running Tests

Unit and Integration Tests

The project employs Jest alongside React Testing Library to facilitate unit and integration testing. This section delineates the procedure to craft and execute tests for the ValidationFramework component:

  1. Dependency Installation: Prior to writing tests, ensure that all requisite testing libraries and dependencies are installed in your project. Use the following command for installation:
   $ npm install --save-dev jest @testing-library/react @testing-library/jest-dom @testing-library/user-event

  1. Test File Creation: Initiate the testing process by creating a new test file named ComponentName.test.js in the same directory as the other tests : ../src/tests/.

  2. Test Writing: Within ComponentName.test.js, commence writing tests to ascertain the functionality of the ComponentName component. For instance, tests could be written to verify form validation logic and form submission behavior.

  3. Test Execution: With the tests written, execute them by running the designated command in your terminal. This command triggers Jest, which autonomously locates and runs all files with a .test.js suffix.

   $ npm test
  1. Test Result Inspection: Post test execution, Jest furnishes a summary of the test outcomes in the terminal. For a more detailed insight into the test results, a coverage report can be generated and reviewed using the following command:
   $ npm test -- --coverage

  1. Test Debugging: In case of test failures, utilize the error messages and stack traces provided by Jest to identify and rectify the issues. Debugging tools and additional Jest features can be employed to further investigate and resolve testing anomalies.

  2. Test Refinement: Based on the test results and debugging, refine your tests to ensure they cover all scenarios and edge cases. This iterative process enhances the robustness and reliability of your tests.

System and end-to-end tests

In the root directory of the app run

$ npx cypress open

and then click on "Run integration tests".

Continuous integration / Continuous delivery

For CI/CD we use the EBRAINS Gitlab server. Certain branches of the Github repository are mirrored.

The config file is .gitlab-ci.yml in the top-level folder of the Git repository. On each commit to the "master" or "staging" branch, all tests are run, then the Docker image for the relevant server is built and pushed to the EBRAINS image registry.

Code style

We use Prettier to maintain uniform code formatting. This integrates with most editors. You can also run the formatter manually, using

npx prettier --write --tab-width 4 .

Making a release

[TODO]

Deployment

The app is deployed using nginx running in a Docker container. To build a Docker image for the staging version:

$ docker build -f deployment/Dockerfile.staging -t docker-registry.ebrains.eu/model-catalog/model-catalog-v2:staging .

(you could replace the Docker tag "staging" with the Git branch name). Note that this build is run automatically by the GitLab CI pipeline (see above).

To build a Docker image for the production version:

$ docker build -f deployment/Dockerfile.prod -t docker-registry.ebrains.eu/model-catalog/model-catalog-v2:latest .

To push an image to the EBRAINS image registry, first ensure you are logged in (see the docker-registry collab for instructions). Then run:

docker push docker-registry.ebrains.eu/model-catalog/model-catalog-v2:latest

On the VM where you wish to deploy the app, run

sudo docker pull docker-registry.ebrains.eu/model-catalog/model-catalog-v2:latest

(replace "latest" with "dev", or another tag as appropriate).

then

sudo docker run -d -v /etc/letsencrypt:/etc/letsencrypt -p 443:443 --name model-catalog-app docker-registry.ebrains.eu/model-catalog/model-catalog-v2:latest

TODO: document how to set up the VM, and how to install the letsencrypt certificate.

Contributing / development workflow

To submit a bug reports or request for enhancements, please use the issue tracker. Before creating a new issue, please first check that there is no existing issue on the same topic. Please give as much information as possible, including screenshots, error messages, etc.

The development workflow is based on pull requests. If you wish to contribute, please:

  • fork the repository
  • base your changes off the most recent development branch
  • use a branch with a meaningful name (no pull requests from branches named "master" or "development")
  • open a pull request, explaining which issue the PR addresses

As noted above, please use Prettier to format your code. Since the app already has several heavy dependencies, please try to minimise use of additional third-party libraries.

Code of Conduct

In the interest of fostering an open and welcoming environment, we expect all developers, maintainers and other contributors to abide by the project Code of Conduct, which you can find in the file CODE_OF_CONDUCT.md at the top level of the Git repository.