fairdataihub · slugb0t · Dec 10, 2024 · Dec 10, 2024 · Dec 10, 2024 · Dec 10, 2024
@@ -186,7 +186,7 @@ baseTemplate = await applyExpectoPatronumTemplate(
 You can provide console logs throughout your feature for debugging purposes and when you run locally you will those logs in the terminal. You can run the following command at the root level to start the both the ui and bot servers. Below is the command and the expected output:
 
 ```bash
-pnpm dev
+yarn dev
 ```
 
 ![Terminal Output](/terminal-output.png)

@@ -8,95 +8,142 @@ head:
       content: https://kalai.fairdataihub.org/api/generate?title=Codefair%20Documentation&description=Running%20the%20GitHub%20Repository&app=codefair&org=fairdataihub
 ---
 
-# :running: Running Locally
+# :computer: Running Locally
 
 This section provides instructions for developers to run the Codefair GitHub repository locally.
 
-## Code structure
+## :file_folder: Code structure
 
 The Codefair repository combines both the Nuxt frontend and the Probot backend to work with the GitHub App. The repository is divided into two main parts:
 
 1. **Frontend**: The frontend is built with [Nuxt.js](https://nuxt.com/) and is responsible for the user interface of the Codefair platform. The frontend is located in the `ui` directory of the repository.
 
 2. **GitHub App**: The GitHub app is built with [Probot](https://probot.github.io/docs/README/) and is responsible for the GitHub App functionality. The backend is located in the `bot` directory of the repository.
 
-## Prerequisites
+3. **Validation Microservice**: The validation microservice is built with [Express.js](https://expressjs.com/) and is responsible for the validation of metadata, licenses, and CWL files. The microservice is located in the `validation` directory of the repository.
+
+## :white_check_mark: Prerequisites
 
 Before you can run the Codefair repository, you will need the following prerequisites:
 
 1. **Node.js**: You will need Node.js installed on your machine to run the Codefair repository. You can download Node.js from the [official Node.js website](https://nodejs.org/).
 
-2. **MongoDB**: You will need a MongoDB database to store the data for the Codefair platform. You can download MongoDB from the [official MongoDB website](https://www.mongodb.com/).
+2. **Database**: Codefair now uses Prisma as an ORM for managing database storage. Ensure you have a supported database (e.g., PostgreSQL, MySQL, or SQLite) set up and configured. You can learn more about Prisma and its supported databases from the [official Prisma website](https://www.prisma.io/).
 
-3. **pnpm**: You will need pnpm installed on your machine to run the Codefair repository. You can install pnpm by running the following command:
+3. **Yarn**: You will need Yarn installed on your machine to run the Codefair repository. You can install Yarn by running the following command:
 
 ```bash
-npm install -g pnpm
+npm install -g yarn
 ```
 
 4. **Smee**: You will need Smee.io to create a webhook proxy for the GitHub App. You can create a Smee.io webhook proxy by visiting the [Smee.io website](https://smee.io/). This will be used to receive GitHub App events from the GitHub API on your local machine.
 
 5. **Oauth App**: Create an Oauth App by going to the Developer Settings in your GitHub account and within the Oauth Apps section. You will need to provide the following information:
 
-- **Application Name**: Name of the Oauth App
-- **Homepage URL**: URL for the Codefair frontend
-- **Authorization callback URL**: URL for the Codefair frontend
+   - **Application Name**: Name of the Oauth App
+   - **Homepage URL**: URL for the Codefair frontend
+   - **Authorization callback URL**: URL for the Codefair frontend
 
 6. **GitHub App**: Create a GitHub App by going to the Developer Settings in your GitHub account and within the GitHub App section. You will need to provide the following information:
 
-- **GitHub App Name**: Name of the GitHub App
-- **Homepage URL**: URL for the Codefair frontend
-- **Webhook URL**: URL for the Probot server (If working locally use the Smee.io URL)
-- **Webhook Secret**: Secret for the GitHub App webhook
-- **Permissions**:
-  - **Read & Write access:** Contents, issues, and pull requests
-  - **Read access:** Metadata
-  - **Events to Subscribe to:** Issue comments, issues, pull request, pull request review, push, repository
+   - **GitHub App Name**: Name of the GitHub App
+   - **Homepage URL**: URL for the Codefair frontend
+   - **Webhook URL**: URL for the Probot server (If working locally use the Smee.io URL)
+   - **Webhook Secret**: Secret for the GitHub App webhook
+   - **Permissions**:
+     - **Read & Write access:** Contents, issues, and pull requests
+     - **Read access:** Metadata
+     - **Events to Subscribe to:** Issue comments, issues, pull request, pull request review, push, repository
 
 For the final question on `Where can this GitHub App be installed?`, you can choose `Any account` to allow the GitHub App to be installed on any repository.
 
 Once you have create the GitHub App, you will need to generate a private key and client secret for the GitHub App. The private key and client secret will be used to authenticate the GitHub App with the GitHub API.
 
-## Running the Repository
+## :wrench: Setting up the Codefair repository
 
 You can run the following commands to start the Codefair repository:
 
 1. **Clone the Repository**: Clone the Codefair repository to your local machine by running the following command:
 
 ```bash
-git clone
+git clone <repository-url>
 ```
 
 2. **Install Dependencies**: Run the following command to install the dependencies for the Codefair repository:
 
 ```bash
-pnpm install
+yarn install
 ```
 
 3. **Gather Environment Variables**: Create a `.env` file in both the `ui` and `bot` directories of the repository. You can use the `.env.example` file as a template for the environment variables.
 
 ```bash
 # .env file in the ui directory
-GITHUB_APP_ID=            # GitHub App ID
-GITHUB_APP_PRIVATE_KEY=   # GitHub App private key
-GITHUB_CLIENT_ID=         # GitHub OAuth client ID
-GITHUB_CLIENT_SECRET=     # GitHub OAuth client secret
-MONGODB_DB_NAME=          # Name of the MongoDB database
-MONGODB_URI=              # URI for the MongoDB database
+GH_APP_ID=            # GitHub App ID
+GH_APP_NAME=          # Name of the GitHub App
+GH_APP_PRIVATE_KEY=   # GitHub App private key
+GH_APP_CLIENT_ID=         # GitHub OAuth client ID
+GH_APP_CLIENT_SECRET=     # GitHub OAuth client secret
+GH_OAUTH_CLIENT_ID=   # GitHub OAuth client ID
+GH_OAUTH_CLIENT_SECRET=   # GitHub OAuth client secret
+PORT=3001             # port for the frontend
+DATABASE_URL=         # URL for the database
+WEBHOOK_PROXY_URL=    # URL for the webhook proxy
+WEBHOOK_SECRET=      # GitHub App webhook secret
+ZENODO_API_ENDPOINT=  # Zenodo API endpoint
+ZENODO_CLIENT_ID=     # Zenodo OAuth client ID
+ZENODO_CLIENT_SECRET= # Zenodo OAuth client secret
+ZENODO_ENDPOINT=      # Zenodo endpoint
+ZENODO_REDIRECT_URI=  # Zenodo redirect URI
 ```
 
 ```bash
 # .env file in the bot directory
 CODEFAIR_APP_DOMAIN=          # http://localhost:3000 or your domain for the frontend
-GITHUB_APP_NAME=              # Name of the GitHub App
-GITHUB_CLIENT_ID=             # GitHub OAuth client ID
-GITHUB_CLIENT_SECRET=         # GitHub OAuth client secret
-MONGODB_DB_NAME=              # Name of the MongoDB database
-MONGODB_URI=                  # URI for the MongoDB database
+GH_APP_NAME=              # Name of the GitHub App
+GH_CLIENT_ID=             # GitHub OAuth client ID
+GH_CLIENT_SECRET=         # GitHub OAuth client secret
 PORT=3001                     # port for the Probot server
+WEBHOOK_SECRET=               # GitHub App webhook secret
 WEBHOOK_PROXY_URL=            # URL for the webhook proxy
 APP_ID=                       # GitHub App ID
-GITHUB_APP_ID=                # GitHub App Id
-PRIVATE_KEY=                  # GitHub App private key
-WEBHOOK_SECRET=               # GitHub App webhook secret
+GH_APP_ID=                    # GitHub App Id
+GH_APP_PRIVATE_KEY=                  # GitHub App private key
+ZENODO_API_ENDPOINT=          # Zenodo API endpoint (sandbox or production)
+ZENODO_ENDPOINT=              # Zenodo url (sandbox or production)
+```
+
+## :running: Running the Codefair repository
+
+There are three main parts to running the Codefair repository:
+
+- **Frontend**: To run the frontend run the following command at the root of the repository:
+
+```bash
+# Navigate to the ui directory, install dependencies, and run the server
+cd ui && yarn install && yarn dev
+```
+
+- **Backend**: To run the backend run the following command at the root of the repository:
+
+```bash
+# Navigate to the bot directory, install dependencies, and run the server
+cd bot && yarn install && yarn dev
+```
+
+- **Validation Microservice**: To run the validation microservice run the following command at the root of the repository:
+
+```bash
+# Create a virtual environment within the validation folder
+cd validation && python -m venv .venv
+
+# Activate the virtual environment
+source .venv/bin/activate  # For Linux or MacOS
+source .venv/Scripts/activate   # For Windows
+
+# Install the requirements
+pip install -r requirements.txt
+
+# Run the microservice
+python app.py --host localhost --port 5000
 ```
@@ -15,10 +15,10 @@ Codefair is a free and open source GitHub app that acts as your personal assista
 <!-- ![dashboard](/dashboard.png){width=10%}
 ![metadata-editor](/metadata-ui.png){width=10%} -->
 
-## How does Codefair work?
+## :question: How does Codefair work?
 
 Simply install Codefair from the [GitHub marketplace](https://github.com/marketplace/codefair-app) on your software's GitHub repository. By communicating with you through GitHub issues and submitting pull requests, Codefair will ensure that your software follows best coding practices, provides metadata in standard formats, includes a license file, is archived on Zenodo, and much more to align with the FAIR4RS principles.
 
-## Who should use Codefair?
+## :busts_in_silhouette: Who should use Codefair?
 
 Currently, Codefair helps make software FAIR by following the [(FAIR Biomedical Research Software (FAIR-BioRS) guidelines)](https://fair-biors.org/). Most of the steps in the FAIR-BioRS guidelines are applicable to any research software, regardless of the field. This means that anyone developing research software can use Codefair. Whether you are developing artificial intelligence (AI)/machine learning (ML) models with Python, data visualization tools with Jupyter Notebook, or data analysis code with R, Codefair is here to assist you.
@@ -20,13 +20,13 @@ There is a webhook method that allows you to [automatically archive each GitHub
 To archive your software on Zenodo, you will need to have a [license file](/docs/license.md) and [metadata files](/docs/metadata.md) (CITATION.cff and codemeta.json) in your repository.
 :::
 
-## How to make a FAIR release
+## :rocket: How to make a FAIR release
 
 To make a FAIR software release, you can simply click on the `Create release` button provided in the GitHub Issue Dashboard under the FAIR Software Release section. This will direct you to the Codefair's UI that takes you step by step into connecting to Zenodo, providing metadata required by Zenodo, making a release on GitHub, and archiving it on Zenodo.
 
 ![Software Archive](/zenodo-dashboard.png)
 
-## FAIR software release UI
+## :desktop_computer: FAIR software release UI
 
 The Zenodo archive UI is a user-friendly interface that allows you to archive your research software. It takes you through several steps:
 
@@ -72,6 +72,6 @@ The Zenodo archive UI is a user-friendly interface that allows you to archive yo
 
 After clicking the `Start the Zenodo publish process` button, Codefair will automatically handle your release. This includes generating a DOI via Zenodo for citation, updating the metadata files (CITATION.cff and codemeta.json) with the new DOI, and finalizing the release on both GitHub and Zenodo. You can monitor the status in both the Codefair UI and GitHub Issue dashboards. Once completed, Codefair will notify you of the successful archival, allowing you to track the entire Zenodo process.
 
-## Workflow Diagram
+## :world_map: Workflow Diagram
 
 ![Zenodo Archive](/zenodo-diagram.png)
@@ -12,19 +12,19 @@ head:
 
 This section provides an overview of the CWL Validation feature of Codefair.
 
-## What is CWL Validation?
+## :newspaper: What is CWL Validation?
 
 The Common Workflow Language (CWL) is a specification for describing analysis workflows and tools in a way that makes them portable and scalable across a variety of software and hardware environments, from workstations to cluster, cloud, and high-performance computing (HPC) environments. The CWL standard is designed to meet the needs of data-intensive science, such as Bioinformatics, Medical Imaging, Astronomy, Physics, and Chemistry. CWL is developed by the [Common Workflow Language working group](https://www.commonwl.org/).
 
 The CWL Validation feature of Codefair will check if the CWL files in a repository are compliant with the CWL standard. The feature will automatically detect CWL files in a repository and submit a pull request with a GitHub action configuration file that includes workflows for checking the syntax and structure of the CWL files. The action will check CWL files on every commit and submit a pull request to address any syntax or structure issue. The feature will make use of existing tools such as [cwltool](https://cwltool.readthedocs.io/en/stable/) and [CWL command line validator](https://cwltool.readthedocs.io/en/stable/cli.html#cmdoption-cwltool-validate).
 
-## CWL Issue Dashboard
+## :bar_chart: CWL Issue Dashboard
 
 The CWL Section on the GitHub issue dashboard will display the CWL validations of the repository. The dashboard will show the status of the CWL validation and provide a link to the view the details of the validation results.
 
 ![CWL Issue Dashboard](/cwl-dashboard.png)
 
-## CWL Validation Results
+## :white_check_mark: CWL Validation Results
 
 The CWL validation results page will display the details of the CWL validation. The page will show the status of the validation, the list of CWL files checked, and the details of the issues found in the CWL files.
 

@@ -10,7 +10,15 @@ head:
 
 # :memo: GitHub Issue Dashboard
 
-As soon as you install the Codefair app, it opens a GitHub issue in your repository. This issue contains a dashboard that provides a point-by-point overview of your software's compliance with elements that make a software FAIR. The dashboard is updated with each new commit to the main branch, when Codefair opens a pull request for you, and when you release to GitHub and archive to Zenodo using Codefair. A check mark is shown next to elements your software is complying with (e.g., the dashboard in screenshot below shows that the software has a LICENSE file). A red cross is shown next to the elements that are not complied with yet (e.g., the dashboard in screenshot below shows that the software does not have required metadata files). For such elements, there is a button that takes you to the Codefair website where you can easily address the compliance issue through a convenience user interface.
+As soon as you install the Codefair app, it opens a GitHub issue in your repository. This issue contains a dashboard that provides a point-by-point overview of your software's compliance with elements that make a software FAIR.
+
+The dashboard is updated with certain events that trigger a check on the repository. These events include:
+
+- Each new commit to the main branch
+- Codefair opens a pull request for you
+- A release to GitHub and archive to Zenodo is made **using** Codefair
+
+A check mark is shown next to elements your software is complying with (e.g., the dashboard in screenshot below shows that the software has a LICENSE file). A red cross is shown next to the elements that are not complied with yet (e.g., the dashboard in screenshot below shows that the software does not have required metadata files). For such elements, there is a button that takes you to the Codefair website where you can easily address the compliance issue through a convenience user interface.
 
 ::: warning
 If you close the issue, Codefair will deactivate until you reopen the issue but if you delete the issue, you will need to reinstall Codefair to that repository.

@@ -12,7 +12,7 @@ head:
 
 This section provides instructions for installing the Codefair GitHub App and the permissions required for the GitHub and Oauth Sign In through the Codefair UI.
 
-## GitHub App Installation
+## :gear: GitHub App Installation
 
 To install the Codefair GitHub App, you will need to follow the steps below:
 
@@ -27,7 +27,7 @@ You can also install the Codefair App without a credit card by visiting the [pub
 
 After following these steps, the Codefair GitHub App will be installed on your repository and you will be able to access the Codefair features.
 
-## GitHub App Permissions
+## :robot: GitHub App Permissions
 
 Codefair requires the following permissions to function correctly:
 
@@ -36,7 +36,7 @@ Codefair requires the following permissions to function correctly:
 
 ![Codefair Permissions](/codefair-permissions.png)
 
-## Oauth Sign in Permissions
+## :key: Oauth Sign in Permissions
 
 Users can sign in to Codefair using their GitHub account. Codefair requires the following permissions to function correctly: