django-ngrok

Expose your local Django app to the internet with ngrok

Quick start

1. Install with pip:

pip install django-ngrok

2. Add django-ngrok to INSTALLED_APPS in your Django settings file:

INSTALLED_APPS = [
    ...
    'django_ngrok',
]

3. Set the NGROK_AUTHTOKEN environment variable to your ngrok authtoken:

export NGROK_AUTHTOKEN="your-ngrok-authtoken"

4. Run python manage.py runserver_ngrok to start a django development server and an ngrok tunnel pointing to the server address. You should expect to see the following output:

Watching for file changes with StatReloader
Performing system checks...

System check identified no issues (0 silenced).
December 13, 2024 - 19:58:42
Django version X.Y.ZZ, using settings 'your.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

ngrok forwarding to http://127.0.0.1:8000 from ingress url: https://your-ngrok-domain.ngrok-free.app

Configuration

django-ngrok uses the forward method from ngrok-python to create a tunnel to the Django development server. If you are using a simple setup, no configuration is necessary, and you can get up-and-running by following the quick start.

For a more explicit setup, you can add the NGROK_CONFIG setting to your Django settings file. All options below are documented here. If you have any questions about how to use these options, please direct them to the ngrok-python maintainers.

NGROK_CONFIG = {
    # session configuration
    "authtoken": str,
    "authtoken_from_env": True | False,  # Defaults to True
    "app_protocol": str,
    "session_metadata": str,
    # advanced session connection configuration
    "server_addr": str,
    "root_cas": str,
    "session_ca_cert": str,
    # listener configuration
    "metadata": str,
    "domain": str,
    "schemes": list[str],
    "proto": str,
    "proxy_proto": str,
    "labels": str,
    # module configuration
    "basic_auth": list[str],
    "circuit_breaker":0.1,
    "compression":True,
    "allow_user_agent": str,
    "deny_user_agent": str,
    "allow_cidr": str,
    "deny_cidr": str,
    "crt": bytes,  # I assume bytes, docs don't specify, haven't tested it.
    "key": bytes,
    "mutual_tls_cas": bytes,
    "oauth_provider": str,
    "oauth_allow_domains": list[str],
    "oauth_allow_emails": list[str],
    "oauth_scopes": list[str],
    "oauth_client_id": str,
    "oauth_client_secret": str,
    "oidc_issuer_url": str,
    "oidc_client_id": str,
    "oidc_client_secret": str,
    "oidc_allow_domains": list[str],
    "oidc_allow_emails": list[str],
    "oidc_scopes": list[str],
    "policy": str,
    "request_header_remove": str,
    "response_header_remove": str,
    "request_header_add": str,
    "response_header_add": str,
    "verify_upstream_tls": True | False,
    "verify_webhook_provider": str,
    "verify_webhook_secret": str,
    "websocket_tcp_converter": True | False,
}

Contributing

Contributions and feedback are welcome! A contribution guide is upcoming, but if you have any questions, please feel free to open an issue or reach out directly.