Skip to content

Latest commit

 

History

History
298 lines (201 loc) · 10.9 KB

CONTRIBUTING.md

File metadata and controls

298 lines (201 loc) · 10.9 KB

Contributing to Nest

Thank you for considering contributing to the OWASP Nest project! This document provides guidelines to help you get started.

About the Project

Nest is a full-stack web application built using:

  • Backend: Python, Django
  • Frontend: TypeScript, React, Tailwind CSS
  • Search: Algolia

The project uses a containerized approach for both development and production environments. Docker is required to run Nest locally.

Prerequisites

Before contributing, ensure you have the following installed:

  1. Docker: Required for running the Nest instance - Docker Documentation.

  2. pre-commit: Required to automate code checks and apply fixes, ensuring consistent and high-quality code. Install it using virtual environment with pip install pre-commit command, as OS package with apt install pre-commit / brew install pre-commit or any other method depending on your configuration.

  3. WSL (Windows Subsystem for Linux): Required for Windows users to enable Linux compatibility - WSL Documentation.

    1. The make run command requires WSL to function properly. Make sure WSL is installed and configured on your system. If you haven't installed WSL yet, follow Microsoft's official guide.
    2. You must use WSL terminal (not Windows PowerShell) otherwise there is no guarantee that Nest development environment will be set up as intended. Please do not report any issues if you use PowerShell for running the commands -- it's not the intended way to run Nest locally so the errors will not be accepted as bugs.
    3. Ensure WSL integration is enabled in Docker Desktop settings by checking Resources -- WSL integration in Docker application settings.

Starring the Project

GitHub stars

Forking the Repository

GitHub forks

Setting up the Project

Follow these steps to set up the OWASP Nest application:

  1. Clone the Repository:

    • Clone the repository code from your GitHub account using the following command:

      git clone https://github.com/<your-account>/<nest-fork>

  2. Create Environment Files:

    • Create a local environment file in the backend directory:

      touch backend/.env

    • Copy the contents from the template file into your new local environment file:

      cat backend/.env.example > backend/.env

    • Create a local environment file in the frontend directory:

      touch frontend/.env

    • Copy the contents from the template file into your new local environment file:

      cat frontend/.env.example > frontend/.env

    Please note you need to restart the application in order to apply any .env file changes.

  3. Configure Environment Variables:

    • Open the backend/.env file in your preferred text editor and change the DJANGO_CONFIGURATION value to Local:

      DJANGO_CONFIGURATION=Local

  4. Set Up Algolia:

    • Go to Algolia and create a free account.

    • After creating an account, create an Algolia app.

    • Update your backend/.env file with the following keys from your Algolia app (use write API key for backend):

      DJANGO_ALGOLIA_APPLICATION_ID=<your-algolia-application-id>
DJANGO_ALGOLIA_WRITE_API_KEY=<your-algolia-write-api-key>
DJANGO_ALGOLIA_APPLICATION_REGION=<your-algolia-application-region> // eu or us

    • Update your frontend/.env file with the following keys from your Algolia app (use search API key for frontend):

      VITE_ALGOLIA_APP_ID=<your-algolia-application-id>
VITE_ALGOLIA_SEARCH_API_KEY=<your-algolia-search-api-key>

    • Ensure that your API key has index write permissions. You can ignore any onboarding wizard instructions provided by Algolia.

  5. Run the Application:

    • In your terminal, navigate to the project root directory (not backend and not frontend subdirectories -- you need the project root directory) Nest has backend and frontend related Makefiles in corresponding directories and all of them are included in the main Makefile in the project root directory. Run the following command to start the application:

      make run

    • Leave this terminal session running and wait until you see that Nest local is responding.

    • Please note as we use containerazed approach this command must be run in parallel to other Nest commands you may want to use. You need to keep it running in the current terminal and use another terminal session for your work.

  6. Load Initial Data:

    • Open a new terminal session and run the following command to populate the database with initial data from fixtures:
    make load-data

  7. Index Data:

    • In the same terminal session, run the following command to index the data:

      make index-data

  8. Verify API Endpoints:

Optional Steps

GitHub Data Fetch

If you plan to fetch GitHub OWASP data locally, follow these additional steps:

  1. Create a Super User:

    • Run the following command to create a super user for accessing the admin interface:

      make setup

  2. Generate a GitHub Personal Access Token:

  3. Update Environment Variables with GitHub Token:

    • Open backend/.env again and update it with your GitHub token:

      GITHUB_TOKEN=<your-github-token>

  4. Sync Local Database Data:

    • Now you should be able to run the following command to sync your local database data with GitHub:

      make sync-data

NestBot Development

To setup NestBot development environment, follow these steps:

  1. Set Up ngrok:

    • Go to ngrok and create a free account.

    • Install and configure ngrok on your machine using these instructions

    • Create your static domain by simply going to ngrok domains

    • Run the following commands to edit ngrok configuration:

      ngrok config edit
      agent:
    authtoken: <your-auth-token>
tunnels:
    NestBot:
      addr: 8000
      proto: http
      hostname: <your-static-domain>

    • Now ngrok is all set, you access your local setup over internet, running the follwing command:

      ngrok start NestBot

  2. Update environment Variables with your NestBot Configuration:

    • Update backend/.env with your Slack application tokens:

      • Bot User OAuth Token from Settings -- Install App -- OAuth Tokens section
      • Signing Secret from Settings -- Basic Information -- App Credentials section
      DJANGO_SLACK_BOT_TOKEN=<your-slack-bot-token>
DJANGO_SLACK_SIGNING_SECRET=<your-slack-signing-secret>

  3. Set up Slack application:

    • Configure your Slack application using NestBot manifest file (copy its contents and save it intoSettings -- App Manifest). You'll need to replace slash commands endpoint with your ngrok static domain path.
    • Reinstall your Slack application after making the changes in Features -- OAuth & Permissions section.

Code Quality Checks

Nest enforces code quality standards to ensure consistency and maintainability. You can run automated checks locally before pushing your changes:

make check

This command runs linters and other static analysis tools for both the frontend and backend. Please note your PR won't be reviewed if it fails the code quality checks.

Testing

Our CI/CD pipelines automatically run tests against every Pull Request. You can run tests locally before submitting a PR:

make test

This command runs tests and checks that coverage threshold requirements are satisfied for both backend and frontend. Please note your PR won't be merged if it fails the code tests checks.

Test Coverage

  • There is a minimum test coverage requirement for the backend code -- see pyproject.toml.
  • There is a minimum test coverage requirement for the frontend code -- see jest.config.ts.
  • Ensure your changes do not drop the overall test coverage percentage.

If you are adding new functionality, include relevant test cases.

Contributing Workflow

1. Find Something to Work On

  • Check the Issues tab for open issues: https://github.com/owasp/nest/issues
  • If you want to work on something specific, create a new issue or comment on an existing one to let others know.

2. Create a Branch

Always create a feature branch for your work:

git checkout -b feature/my-feature-name

3. Make Changes and Commit

  • Check that your commits include only related and intended changes. Do not include unrelated files.

  • Follow best practices for code style and testing.

  • Add tests for any new functionality or changes to ensure proper coverage.

  • Run the code quality checks:

    make check

  • Run tests to ensure everything works correctly:

    make test

  • Write meaningful commit messages:

    git commit -m "Add feature: short description"

4. Push Changes

  • Push your branch to the repository:

    git push origin feature/my-feature-name

5. Open a Pull Request

  • Submit a Pull Request (PR) to the main branch.
  • Your PR will trigger CI/CD pipelines that run automated checks and tests.

6. Review and Merge

  • Address feedback from maintainers during code review.
  • Once approved, your PR will be merged into the main branch.

Code of Conduct

Please follow the Code of Conduct when interacting with other contributors.

Thank you for contributing to Nest! Your contributions help make this project better for everyone.