Skip to content

Ngrok

Overview

The dev_tool integrates ngrok to expose your local Django development server to the internet through a secure tunnel. This is useful for testing webhooks, sharing your local environment with others, or accessing your development server from external services.

Prerequisites

  • An ngrok account with an auth token
  • The NGROK_AUTHTOKEN environment variable set in your development.env
  • The NGROK_URL environment variable set in your development.env (optional, used by Django for ALLOWED_HOSTS and CSRF_TRUSTED_ORIGINS)

Configuration

development.env

Add the following environment variables to your development.env file:

NGROK_AUTHTOKEN=your_ngrok_auth_token_here
NGROK_URL=https://your-subdomain.ngrok-free.app
Variable Description
NGROK_AUTHTOKEN Your ngrok authentication token. This is found in the ngrok dashboard.
NGROK_URL The public ngrok URL. It is used by the Django settings block below to configure ALLOWED_HOSTS and CSRF_TRUSTED_ORIGINS.

Django Settings

Your project's base_settings.py (or equivalent) must include the following block to allow ngrok traffic through Django's host and CSRF validation:

NGROK_URL = os.environ.get('NGROK_URL')

if NGROK_URL:
    ALLOWED_HOSTS.append(NGROK_URL.replace('https://', '').replace('http://', ''))
    CSRF_TRUSTED_ORIGINS = [NGROK_URL]

When NGROK_URL is set, this will:

  • Add the ngrok hostname to ALLOWED_HOSTS
  • Add the ngrok URL to CSRF_TRUSTED_ORIGINS

How It Works

When the dev_tool starts the Django development server with ngrok enabled, the NgrokService creates a secure tunnel that forwards traffic from the public ngrok URL to your local server. The tunnel remains active for the duration of the development server session and is automatically stopped when the server is shut down.

Getting an Auth Token

  1. Create a free account at ngrok.com
  2. Navigate to Your Authtoken in the ngrok dashboard
  3. Copy the token and add it to your development.env as NGROK_AUTHTOKEN