GitHubEmailContact
Skip to main content

Ngrok Configuration Reference

Complete reference for configuring ngrok integration in Django-CFG.

Basic Configuration​

from django_cfg import DjangoConfig, NgrokConfig

class MyConfig(DjangoConfig):
    project_name: str = "My Project"

    # Enable ngrok for webhook development
    ngrok: NgrokConfig = NgrokConfig(
        enabled=True,  # Enable ngrok (only in DEBUG=True)
        auto_start=True,  # Auto-start with runserver_ngrok
        webhook_path="/api/webhooks/",  # Path for webhook URLs
        update_api_url=True  # Automatically update api_url
    )

config = MyConfig()

NgrokConfig Fields​

FieldTypeDefaultDescription
enabledboolFalseEnable ngrok integration (only works when DEBUG=True)
auto_startboolTrueAutomatically start tunnel when using runserver_ngrok
webhook_pathstr"/webhooks/"Default path for webhook URLs
update_api_urlboolTrueAutomatically update api_url with tunnel URL
authNgrokAuthConfigNoneAuthentication configuration
tunnelNgrokTunnelConfigNoneTunnel-specific settings

Advanced Configuration​

With Authentication​

For advanced ngrok features like custom domains, you need an auth token:

from django_cfg import NgrokConfig, NgrokAuthConfig

ngrok: NgrokConfig = NgrokConfig(
    enabled=True,

    # Authentication
    auth=NgrokAuthConfig(
        authtoken_from_env=True  # Load from NGROK_AUTHTOKEN env var
    )
)

Or provide token directly:

ngrok: NgrokConfig = NgrokConfig(
    enabled=True,

    auth=NgrokAuthConfig(
        authtoken="your_ngrok_token_here"  # Not recommended for production
    )
)

NgrokAuthConfig Fields​

FieldTypeDefaultDescription
authtokenstrNoneNgrok auth token (get from ngrok.com)
authtoken_from_envboolFalseLoad auth token from NGROK_AUTHTOKEN environment variable

With Custom Tunnel Settings​

Advanced tunnel configuration for paid ngrok plans:

from django_cfg import NgrokConfig, NgrokTunnelConfig

ngrok: NgrokConfig = NgrokConfig(
    enabled=True,

    # Tunnel settings
    tunnel=NgrokTunnelConfig(
        domain="myapp.ngrok.io",  # Custom domain (paid plan)
        basic_auth=["admin:secret"],  # Password protect tunnel
        compression=True,  # Enable gzip compression
        bind_tls=True,  # Force HTTPS
    )
)

NgrokTunnelConfig Fields​

FieldTypeDefaultDescription
domainstrNoneCustom ngrok domain (requires paid plan)
basic_authList[str]NoneBasic auth credentials (format: ["user:pass"])
compressionboolFalseEnable gzip compression
bind_tlsboolTrueForce HTTPS connections
inspectboolTrueEnable ngrok web interface

Environment Variables​

Set by Django-CFG​

When you run python manage.py runserver_ngrok, Django-CFG automatically sets these environment variables:

VariableExampleDescription
NGROK_URLhttps://abc123.ngrok.ioFull tunnel URL
NGROK_HOSTabc123.ngrok.ioTunnel hostname
NGROK_SCHEMEhttpsProtocol scheme

Usage in code:

import os

# Get tunnel URL
ngrok_url = os.environ.get('NGROK_URL')  # "https://abc123.ngrok.io"

# Build webhook URL
webhook_url = f"{ngrok_url}/api/webhooks/stripe/"

Required Environment Variables​

For advanced ngrok features:

# Ngrok auth token (optional, for paid features)
export NGROK_AUTHTOKEN="your_ngrok_token"

Configuration Examples​

Example 1: Development Only​

from django_cfg import DjangoConfig, NgrokConfig
from .environment import env

class MyConfig(DjangoConfig):
    # Ngrok only in development
    ngrok: NgrokConfig = NgrokConfig(
        enabled=(env.environment == "development"),
        webhook_path="/api/webhooks/"
    )

Example 2: With Custom Domain​

from django_cfg import NgrokConfig, NgrokAuthConfig, NgrokTunnelConfig

ngrok: NgrokConfig = NgrokConfig(
    enabled=True,

    auth=NgrokAuthConfig(
        authtoken_from_env=True  # Load from NGROK_AUTHTOKEN
    ),

    tunnel=NgrokTunnelConfig(
        domain="myapp.ngrok.io",  # Custom domain
        compression=True
    )
)

Example 3: With Password Protection​

ngrok: NgrokConfig = NgrokConfig(
    enabled=True,

    tunnel=NgrokTunnelConfig(
        # Protect tunnel with basic auth
        basic_auth=["admin:supersecret"],
        bind_tls=True  # Force HTTPS
    )
)

Example 4: Environment-Specific​

from .environment import env

class MyConfig(DjangoConfig):
    # Different settings per environment
    ngrok: NgrokConfig = NgrokConfig(
        enabled=(env.environment == "development"),
        webhook_path=(
            "/webhooks/"  # Development
            if env.environment == "development"
            else None  # Production
        )
    )

    # Use ngrok URL in dev, real URL in prod
    api_url: str = (
        "https://api.myapp.com"
        if env.environment == "production"
        else "http://localhost:8000"
    )

Configuration Best Practices​

1. Use Environment Variables​

# ✅ CORRECT - load from environment
ngrok: NgrokConfig = NgrokConfig(
    enabled=True,
    auth=NgrokAuthConfig(
        authtoken_from_env=True  # From NGROK_AUTHTOKEN
    )
)

# ❌ WRONG - hardcode token
ngrok: NgrokConfig = NgrokConfig(
    enabled=True,
    auth=NgrokAuthConfig(
        authtoken="hardcoded-token"  # Security risk!
    )
)

2. Development Only​

# ✅ CORRECT - automatically disabled in production
ngrok: NgrokConfig = NgrokConfig(
    enabled=True  # Only works when DEBUG=True
)

# Even better - explicit environment check
from .environment import env

ngrok: NgrokConfig = NgrokConfig(
    enabled=(env.environment == "development")
)

3. Type-Safe Configuration​

# ✅ CORRECT - use Pydantic models
from django_cfg import NgrokConfig

ngrok: NgrokConfig = NgrokConfig(
    enabled=True,
    webhook_path="/api/webhooks/"  # Type-checked!
)

# ❌ WRONG - raw Django settings
# NGROK_ENABLED = True
# NGROK_WEBHOOK_PATH = "/api/webhooks/"  # No validation!

Validations​

Django-CFG automatically validates your ngrok configuration:

# ❌ This will raise ValidationError
ngrok: NgrokConfig = NgrokConfig(
    enabled=True,
    tunnel=NgrokTunnelConfig(
        domain="invalid domain with spaces"  # ValidationError!
    )
)

# ✅ Correct configuration
ngrok: NgrokConfig = NgrokConfig(
    enabled=True,
    tunnel=NgrokTunnelConfig(
        domain="myapp.ngrok.io"  # Valid!
    )
)

Next Steps​

See Also​

Ngrok Integration​

Core Documentation:

Configuration & Setup​

Configuration:

Getting Started:

Payment & Webhook Features​

Payment Integration:

Related Integrations:

Tools & Development​

CLI & Management:

Examples:

Last updated on