Skip to content

Backend

The OWASP Nest backend is a Python-based API server built with the Django framework.

Tech Stack

Component Technology
Framework Django 6.x
REST API Django Ninja
GraphQL API Strawberry GraphQL
Database PostgreSQL
Caching Redis (via django-redis)
Task Queue Django RQ
Search Algolia

Directory Structure

The backend code lives in this directory. Key directories include:

  • src/apps/ - Contains all Django applications (e.g., owasp, github, api).
  • src/settings/ - Django configuration files.
  • tests/ - Automated tests.
  • data/ - Database dumps and backup files.

Running Locally

The project uses Docker for local development. From the project root:

# Start all services (backend, db, cache, …)
make run

Or with Compose directly (add -f docker-compose/local/compose.override.yaml if you use local overrides):

docker compose -f docker-compose/local/compose.yaml up

For local-only volume name customization on a feature branch (parallel checkouts / PR work), edit docker-compose/local/compose.override.yaml and see docker-compose/README.md. Merge queue (not PR CI) rejects non-canonical volume names before they reach main.

For common tasks, use the provided makefile targets:

Task Command
Create database migrations make migration
Run database migrations make migrate
Create a superuser make create-superuser
Run backend tests make test-backend
Access Django shell make shell-django

See the root makefile and the local makefile for more targets.

Key APIs

  • REST API (v0): Served at /api/v0/. See API v0 README for SDK-related constraints.
  • GraphQL API: Served at /graphql/.

Dependencies

Dependencies are managed with Poetry. The main configuration is in pyproject.toml.

# Update dependencies
cd backend && poetry update

External Documentation

Environment Variables

The backend uses the following environment variables (configured in backend/.env):

DJANGO_ALGOLIA_APPLICATION_ID

  • Description: The application ID for Algolia.
  • Example Value: APPID123
  • Usage: Used by Django to initialize Algolia client for indexing/search.

DJANGO_ALGOLIA_EXCLUDED_LOCAL_INDEX_NAMES

  • Description: Index names to exclude locally (if any).
  • Usage: Prevents specific indices from being created in local environments.

DJANGO_ALGOLIA_WRITE_API_KEY

  • Description: The write API key for Algolia.
  • Usage: Required for Django backend to write data into Algolia indices.

DJANGO_ALLOWED_HOSTS

  • Description: A comma-separated list of allowed hosts for the application.
  • Example Value: localhost,127.0.0.1
  • Usage: Restricts HTTP Host header to prevent host header attacks.

DJANGO_AWS_ACCESS_KEY_ID

  • Description: AWS access key ID.
  • Usage: Used for authenticating with AWS services (e.g., S3).

DJANGO_AWS_SECRET_ACCESS_KEY

  • Description: AWS secret access key.
  • Usage: Used along with access key ID to authenticate AWS API requests.

DJANGO_CONFIGURATION

  • Description: Specifies the Django configuration to use.
  • Example Value: Production
  • Usage: Determines which Django settings class to load.

DJANGO_DB_HOST

  • Description: The hostname of the database server.
  • Example Value: db
  • Usage: Used to connect Django to the correct PostgreSQL server.

DJANGO_DB_NAME

  • Description: The name of the database.
  • Example Value: nest
  • Usage: Specifies the name of the PostgreSQL database used by Django.

DJANGO_DB_PASSWORD

  • Description: The password for the database user.
  • Usage: Authenticates the Django DB user.

DJANGO_DB_PORT

  • Description: The port number for the database server.
  • Example Value: 5432
  • Usage: Specifies the port for connecting to PostgreSQL.

DJANGO_DB_USER

  • Description: The username for the database.
  • Example Value: postgres
  • Usage: Authenticates with the database.

DJANGO_ELEVENLABS_API_KEY

  • Description: The API key for ElevenLabs text-to-speech service.
  • Usage: Used for audio generation features.

DJANGO_OPEN_AI_SECRET_KEY

  • Description: The secret key for OpenAI API.
  • Usage: Used for OpenAI integration.

DJANGO_PUBLIC_IP_ADDRESS

  • Description: The IP address to use locally.
  • Usage: Geographic location related functionality.

DJANGO_RELEASE_VERSION

  • Description: The release version of the application.
  • Example Value: 1.0.5
  • Usage: Identifies the current backend deployment version.

DJANGO_REDIS_AUTH_ENABLED

  • Description: Whether Redis requires authentication.
  • Example Value: True
  • Usage: Enables password authentication for Redis when set to True.

DJANGO_REDIS_HOST

  • Description: The hostname of the Redis server.
  • Example Value: cache
  • Usage: Used to connect Django to Redis for caching and task queues.

DJANGO_REDIS_PASSWORD

  • Description: The password for Redis authentication.
  • Usage: Authenticates with Redis when DJANGO_REDIS_AUTH_ENABLED is True.

DJANGO_SECRET_KEY

  • Description: The secret key for Django (used for cryptographic signing).
  • Example Value: Generate with openssl rand -base64 32
  • Usage: Required for session management, tokens, etc. Must be set in backend/.env before starting the backend locally.

DJANGO_SENTRY_DSN

  • Description: The DSN for Sentry (used for error tracking).
  • Example Value: https://xyz@sentry.io/654321
  • Usage: Enables backend error tracking through Sentry.

DJANGO_SLACK_BOT_TOKEN

  • Description: The token for the Slack bot.
  • Usage: Authenticates the bot to send messages to Slack channels.

DJANGO_SLACK_SIGNING_SECRET

  • Description: The signing secret for Slack.
  • Usage: Used to verify Slack requests to webhooks.

GITHUB_TOKEN

  • Description: The token for accessing GitHub APIs.
  • Usage: Used for making authenticated requests to GitHub (e.g., issues, releases).