Skip to content

Commit

Permalink
Update README with Edges example.
Browse files Browse the repository at this point in the history
  • Loading branch information
alexdlaird committed Nov 4, 2024
1 parent 5c621aa commit ba51303
Showing 1 changed file with 34 additions and 3 deletions.
37 changes: 34 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,8 @@ the command line.

## Basic Usage

### Open a Tunnel

To open a tunnel, use the [`connect`](https://pyngrok.readthedocs.io/en/latest/api.html#pyngrok.ngrok.connect) method,
which returns a `NgrokTunnel`, and this returned object has a reference to the public URL generated by `ngrok` in its
`public_url` attribute.
Expand All @@ -57,6 +59,35 @@ The [`connect`](https://pyngrok.readthedocs.io/en/latest/api.html#pyngrok.ngrok.
well, which allows us to pass additional properties that
are [supported by `ngrok`](https://ngrok.com/docs/agent/config/v2/#tunnel-configurations).

### `ngrok`'s Edges

To use [`ngrok`'s Edges](https://ngrok.com/docs/network-edge/edges/) with `pyngrok`, first [configure an Edge on
`ngrok`'s dashboard](https://dashboard.ngrok.com/edges) (with at least one Endpoint mapped to the Edge), and define a
labeled tunnel in [the `ngrok` config file](https://ngrok.com/docs/agent/config/v2/#define-two-labeled-tunnels)
that points to the Edge.

```yaml
tunnels:
some-edge-tunnel:
labels:
- edge=my_edge_id
addr: http://localhost:80
```
To start a labeled tunnel in `pyngrok`, pass its `name`
to [connect](https://pyngrok.readthedocs.io/en/develop/api.html#pyngrok.ngrok.connect).

```python
from pyngrok import ngrok
# Open the Edge tunnel that is defind in the config file
named_tunnel = ngrok.connect(name="some-edge-tunnel")
```

Once an Edge tunnel is started, it can be managed through [`ngrok`'s dashboard](https://dashboard.ngrok.com/edges).

### Command Line Usage

This package puts the default `ngrok` binary on our path, so all features of `ngrok` are
available on the command line.

Expand All @@ -75,13 +106,13 @@ at [http://pyngrok.readthedocs.io](http://pyngrok.readthedocs.io).
### `ngrok` Version Compatibility

`pyngrok` is compatible with `ngrok` v2 and v3, but by default it will install v3. To install v2 instead,
[set `ngrok_version` to "v2" in `PyngrokConfig`](https://pyngrok.readthedocs.io/en/latest/index.html#ngrok-version-compatibility).
[set `ngrok_version` to "v2" in
`PyngrokConfig`](https://pyngrok.readthedocs.io/en/latest/index.html#ngrok-version-compatibility).

## Contributing

If you would like to get involved, be sure to review
the [Contribution Guide](https://github.com/alexdlaird/pyngrok/blob/main/CONTRIBUTING.rst).

Want to contribute financially? If you've found `pyngrok` useful, [sponsorship](https://github.com/sponsors/alexdlaird)
would
also be greatly appreciated!
would also be greatly appreciated!

0 comments on commit ba51303

Please sign in to comment.