Metadata-Version: 2.4
Name: django-ngrok
Version: 0.1.0
Summary: Expose your local Django app to the internet with ngrok
Project-URL: Repository, https://github.com/samamorgan/django-ngrok
Project-URL: Issues, https://github.com/samamorgan/django-ngrok/issues
Author-email: Sam Morgan <sama4mail@gmail.com>
License: # MIT License
        
        _Copyright (c) 2024 Sam Morgan_
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        **THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.**
License-File: LICENSE.md
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Requires-Dist: django>=4.2.17
Requires-Dist: ngrok>=1.4.0
Description-Content-Type: text/markdown

# 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:

```python
INSTALLED_APPS = [
    ...
    'django_ngrok',
]
```

3. Set the `NGROK_AUTHTOKEN` environment variable to [your ngrok authtoken](https://dashboard.ngrok.com/get-started/your-authtoken):

```bash
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`](https://github.com/ngrok/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](#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](https://github.com/ngrok/ngrok-python#full-configuration). If you have any questions about how to use these options, please direct them to the `ngrok-python` maintainers.

```python
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.
