Rewrite Quickstart to use Traffic Policy #1050
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
joelhans
changed the title
|
|
||
| ## Step 1: Install | ||
| <ol className="marker:text-xl marker:font-bold marker:text-blue-500 pl-8"> |
There was a problem hiding this comment.
this layout looks a little strange to me. can we use something more simple like in https://ngrok.com/docs/traffic-policy/getting-started/#prerequisites ?
| This quickstart will use the [ngrok agent](/agent/) to put your application on | ||
| the internet and secure it so that only you can access it. It assumes you already have your | ||
| own application running locally. | ||
| <p className="text-lg"> |
There was a problem hiding this comment.
i don't think this needs to be in large text. normal size is ok.
|
|
||
| ```bash | ||
| ngrok config add-authtoken <TOKEN> | ||
| ngrok http 8080 |
There was a problem hiding this comment.
earlier, we told them to have something running on port 8000, now we are using port 8080. might cause confusion.
| Version 3.0.0 | ||
| Region United States (us) | ||
| Latency 78ms | ||
| Account Foo Bar (Plan: All) |
There was a problem hiding this comment.
we can come up with something better than foo bar here IMO :)
There was a problem hiding this comment.
and the plan should be Free
| Web Interface http://127.0.0.1:4040 | ||
| Forwarding https://84c5df474.ngrok-free.dev -> http://localhost:8080 | ||
| Forwarding https://<GENERATED_NGROK_DOMAIN> -> http://localhost:8080 |
There was a problem hiding this comment.
this port should be updated as well
| ```yaml | ||
| on_http_request: | ||
| - expressions: | ||
| - ""conn.ts.start < timestamp('2999-12-31T23:59:59Z')"" |
There was a problem hiding this comment.
this expression doesn't make much sense. can we use something someone might actually use here as an example?
| ``` | ||
| ngrok http http://localhost:8080 --oauth=google [email protected] | ||
|
|
||
| <p className="text-xl">`on_http_request`</p> |
There was a problem hiding this comment.
this is a quickstart guide. IMO i'm not sure we need to explain all this stuff to them here. if the goal is to add oauth, let's just focus on that and skip this section IMO.
|
|
||
| ### Secure your service with OAuth or basic auth | ||
|
|
||
| Let's say you want to restrict access only to you and your coworkers by |
There was a problem hiding this comment.
I think the language here should be more focused. instead of "let's say", we should just say "We are going to restrict access to your endpoint"
| requiring a successful OAuth log-in with Google, denying anyone who tries to | ||
| login using an email that doesn't belong to your company's domain name. | ||
|
|
||
| Create your first Traffic Policy rule by creating a new file called `auth.yaml` |
There was a problem hiding this comment.
do we need to use a policy file here? why not the command line flags? this is a quickstart after all.
| - Detaching a Tmux session (optional): If you're familiar with Tmux, you can detach your ngrok session from your terminal window. (Note: This is an advanced option). Refer to a guide on using [Tmux](https://www.digitalocean.com/community/tutorials/how-to-configure-tmux-on-a-cloud-server) for more information: | ||
| ngrok supports many forms of authentication: | ||
|
|
||
| <div className="ngrok--cards ngrok--cards-flex ngrok--cards-row"> |
| </div> | ||
| </Link> | ||
| </div> | ||
| <div className="ngrok--cards ngrok--cards-flex ngrok--cards-row"> |
There was a problem hiding this comment.
i'm not sure i'd consider this an "authentication method"
| - Systemd service (Linux): For systemd-based systems, you can create a systemd service to automatically start and manage ngrok. Refer to the documentation for [Systemd service creation](/agent/#background-service). | ||
| - Windows service (Windows): For Windows systems, you can create a Windows service to automatically start and manage ngrok. Refer to the documentation for [Background Service](/agent/#background-service). | ||
| - Detaching a Tmux session (optional): If you're familiar with Tmux, you can detach your ngrok session from your terminal window. (Note: This is an advanced option). Refer to a guide on using [Tmux](https://www.digitalocean.com/community/tutorials/how-to-configure-tmux-on-a-cloud-server) for more information: | ||
| ngrok supports many forms of authentication: |
There was a problem hiding this comment.
I think if you changed this to be something more generic like "ways to protect access to your endpoint, then you can get away with ip restrictions and webhook verification.
|
|
||
| </TabItem> | ||
|
|
||
| <TabItem value="docker" label="Docker"> |
There was a problem hiding this comment.
it's not clear to me why docker is under the "run persistly" section.
| See our [Docker docs](/docs/using-ngrok-with/docker/) for more details. | ||
|
|
||
| </TabItem> | ||
| <TabItem value="detach" label="Tmux/Screen/Zellij"> |
There was a problem hiding this comment.
this doesn't actually tell you how to run persistently on any of these systems. how do you detach it?
Been thinking about the quickstart a lot lately—wanted to take a stab at rewriting this to direct folks toward Traffic Policy and follow the general movement from tunnels->agent endpoints, etc.
The goals here:
Some things to consider:
ngrok http 8080 --oauth googleand that would instantiate a Traffic Policy on the endpoint for you, in which case that would once again be the smoothest path for new users.I think this holds us over for a bit, but we'll also want to start considering the implications of new things like creating cloud endpoints in the UI, cloud+internal setups, etc.
Also, the SDK+K8s quickstarts also need some love.