Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:

Docker

Required for running the containerized development environment

pre-commit

Required to automate code quality checks

gzip

Required for loading database fixtures

WSL (Windows Only)

Required for Windows users to enable Linux compatibility
Windows Users: You must use WSL terminal (not PowerShell). Ensure WSL integration is enabled in Docker Desktop settings under Resources → WSL integration.Do not clone or run the project under /mnt/c (Windows C: drive) as this causes significant performance issues.

​
Initial Setup

1

Fork and Clone the Repository

Fork the repository on GitHub and clone it to your local machine:
git clone https://github.com/<your-account>/<nest-fork>
cd Nest
2

Create Environment Files

Copy the example environment files for both backend and frontend:
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env
Ensure all .env files are saved in UTF-8 format without BOM (Byte Order Mark) to prevent “Unexpected character” errors.
3

Configure Django Settings

Open backend/.env and set the Django configuration to Local:
backend/.env
DJANGO_CONFIGURATION=Local
4

Set Up Algolia Search

OWASP Nest uses Algolia for search functionality:
  1. Create a free account at Algolia
  2. An Algolia app is automatically created during signup (you can skip data import)
  3. Get your Application ID and Write API Key from the Algolia dashboard
  4. Update backend/.env with your credentials:
backend/.env
DJANGO_ALGOLIA_APPLICATION_ID=<your-algolia-application-id>
DJANGO_ALGOLIA_WRITE_API_KEY=<your-algolia-write-api-key>
The Write API key must have addObject permission (index write permissions). The default write key includes this.
5

Start the Application

From the project root directory, start all services with Docker Compose:
make run
This command builds and starts:
  • PostgreSQL database with pgvector extension
  • Redis cache
  • Django backend server (port 8000)
  • Next.js frontend development server (port 3000)
  • Background worker for async tasks
Keep this terminal session running. Open a new terminal for subsequent commands.
Wait until you see the backend responding at http://localhost:8000/api/v0
6

Load Initial Data

In a new terminal, load the database fixtures:
make load-data
This restores the PostgreSQL database dump with sample OWASP data.
7

Index Search Data

Index the data to Algolia for search functionality:
make index-data
This command runs:
  • algolia_reindex - Indexes all data to Algolia
  • algolia_update_replicas - Configures search replicas
  • algolia_update_synonyms - Updates search synonyms
8

Verify Setup

Check that all endpoints are available:

REST API

Django REST Framework API

GraphQL

Strawberry GraphQL endpoint

Frontend

Next.js application

Django Admin

Django admin panel (requires superuser)

​
Optional Setup

​
Create a Superuser

To access the Django admin interface: 
make create-superuser
Follow the prompts to set up admin credentials.

​
GitHub Data Sync

To fetch live OWASP data from GitHub:
  1. Create a GitHub Personal Access Token
  2. Add it to backend/.env:
backend/.env
GITHUB_TOKEN=<your-github-token>
  1. Sync data from GitHub:
make sync-data
This command updates projects, chapters, committees, and contribution data.

​
Access Internal Dashboards

Some UI sections require specific Django user permissions.

​
Project Health Dashboard (Staff Access)

  1. Open Django Admin at http://localhost:8000/a
  2. Navigate to GitHub Users and open your user record
  3. Enable the is_owasp_staff checkbox in the Permissions section
  4. Save changes
  5. Clear browser cookies for localhost:3000 and sign in again
Access the dashboard at http://localhost:3000/projects/dashboard

​
Mentorship Portal

Grant access as a Project Leader:
  1. Open Django Admin → OWASP → Projects
  2. Open or create a project
  3. Add your GitHub username to the leaders_raw field
  4. Save the project
  5. Clear browser cookies and sign in again
Or grant access as a Mentor:
  1. Ensure you’ve logged into the frontend once
  2. Open Django Admin → Mentorship → Mentors
  3. Click Add Mentor and select your GitHub user
  4. Save changes
  5. Clear cookies and sign in again

​
NestBot Development

Never install your development Slack app in the OWASP Slack workspace. This interferes with production NestBot functionality.Always use a separate workspace for testing.
  1. Create a free account at ngrok
  2. Install and configure ngrok using these instructions
  3. Create a static domain at ngrok domains
  4. Edit ngrok configuration:
ngrok config edit
Add this configuration:
agent:
  authtoken: <your-auth-token>
tunnels:
  NestBot:
    addr: 8000
    proto: http
    hostname: <your-static-domain>
  1. Start ngrok tunnel:
ngrok start NestBot
  1. Configure Slack app using the NestBot manifest
  2. Update backend/.env with Slack credentials:
backend/.env
DJANGO_SLACK_BOT_TOKEN=<your-slack-bot-token>
DJANGO_SLACK_SIGNING_SECRET=<your-slack-signing-secret>
  1. Restart the application with make run

​
Common Commands

make run

​
Environment Variables

See the Environment Variables documentation for a complete list of configuration options.

​
Troubleshooting

This is usually caused by incorrect .env file encoding.Solution: Open .env files in your text editor and save as “UTF-8 without BOM”:
  • In VS Code: Click encoding in bottom-right → “Save with Encoding” → “UTF-8”
  • Restart the application with make run
Another process is using ports 3000, 8000, or 5432.Solution:
# Stop all containers
make clean-docker

# Or check what's using the port (example for 8000)
lsof -i :8000
Docker volume permissions issue on Windows.Solution: Ensure your project is not under /mnt/c. Clone it to your WSL home directory:
cd ~
git clone https://github.com/<your-account>/<nest-fork>
Build cache corruption or network issues.Solution:
# Clean Docker resources
make clean-docker

# Prune build cache
make prune

# Rebuild
make run

​
Next Steps

Architecture

Understand the system architecture

Backend Development

Learn about Django backend development

Frontend Development

Learn about Next.js frontend development

Testing

Write and run tests

Build docs developers (and LLMs) love

Get started for freeTalk to us