Repository files navigation

Poor man's ngrok

The pgrok is a multi-tenant HTTP/TCP reverse tunnel solution through remote port forwarding from the SSH protocol.

This is intended for small teams that need to expose the local development environment to the public internet, and you need to bring your own domain name and SSO provider.

It gives stable subdomain for every user, and gated by your SSO through OIDC protocol.

Think of this as a bare-bones alternative to thengrok's $65/user/month enterprise tier. Trying to put this behind a production system will blow up your SLA.

For individuals and production systems, just buy ngrok, it is still my favorite.

Stable subdomains and SSO are two things too expensive.

Why not just pick one from theAwesome Tunneling? Think broader. Not everyone is a dev who knows about server operations. For people working as community managers, sales, and PMs, booting up something locally could already be a stretch and requiring them to understand how to set up and fix server problems is a waste of team's productivity.

Copy, paste, and run is the best UX for everyone.

Before you get started, make sure you have the following:

1. A domain name (e.g.example.com, this will be used as the example throughout this section).
2. A server (dedicated server, VPS) with a public IP address (e.g.111.33.5.14).
3. An SSO provider (e.g. Google, Okta, Keycloak) that allows you to create OIDC clients.
4. A PostgreSQL server (bit.io, Cloud SQL, self-host).

Note:

1. All values used in this document are just examples, substitute based on your setup.
2. HTTPS for the web and proxy server is not required for this to work, while recommended if possible. Examples in this document all use HTTP.

1. Add the following DNS records for your domain name:
   1. A record forexample.com to111.33.5.14
   2. A record for*.example.com to111.33.5.14
2. Set up the server with thesingle binary,Docker orDocker Compose.
3. Alter your network security policy (if applicable) to allow inbound requests to port 2222 from0.0.0.0/0 (anywhere).
4. Download and install Caddy 2 on your server, and use the following Caddyfile config:

   http://example.com {    reverse_proxy* localhost:3320}http://*.example.com {    reverse_proxy* localhost:3000}

5. Create a new OIDC client in your SSO with theRedirect URI to behttp://example.com/-/oidc/callback.

1. Go tohttp://example.com, authenticate with your SSO to obtain the token and URL (e.g.http://unknwon.example.com).
2. Download the latest version of thepgrok:
   • For Homebrew:

     brew install pgrok/tap/pgrok

   • For others, download the archive from theReleases page.
3. Initialize apgrok.yml file with the following command (assuming you want to forward requests tohttp://localhost:3000):

   pgrok init --remote-addr example.com:2222 --forward-addr http://localhost:3000 --token {YOUR_TOKEN}

   • By default, the config file is created under thestandard user configuration directory (XDG_CONFIG_HOME):
     • macOS:~/Library/Application Support/pgrok/pgrok.yml
     • Linux:~/.config/pgrok/pgrok.yml
     • Windows:%LOCALAPPDATA%\pgrok\pgrok.yml
   • Use--config flag to specify a different path for the config file.
4. Launch the client by executing thepgrok orpgrok http command.
   • By default,pgrok expects thepgrok.yml is available under the standard user configuration directory, or under the home directory (~/.pgrok/pgrok.yml). Use--config flag to specify a different path for the config file.
   • Use the--debug flag to turn on debug logging.
   • Upon successful startup, you should see a log looks like:

     🎉 You're ready to go live at http://unknwon.example.com! remote=example.com:2222

5. Now visit the URL.

As a special case, the first argument of thepgrok http can be used to specify forward address, e.g.

pgrok http 8080

Note:

You need to alter the server network security policy (if applicable) to allow additional inbound requests to port range 10000-15000 from0.0.0.0/0 (anywhere).

Use thetcp subcommand to tunnel raw TCP traffic:

pgrok tcp 5432

Upon successful startup, you should see a log looks like:

🎉 You're ready to go live at tcp://example.com:10086! remote=example.com:2222

The assigned TCP port on the server side is semi-stable, such that the same port number is used when still available.

Following config options can be overridden through CLI flags for bothhttp andtcp subcommands:

• --remote-addr, -r ->remote_addr
• --forward-addr, -f ->forward_addr
• --token, -t ->token

Typical HTTP reverse tunnel solutions only support forwarding requests to a single address,pgrok can be configured to have dynamic forward rules when tunneling HTTP requests.

For example, if your local frontend is running athttp://localhost:3000 but some gRPC endpoints need to talk to the backend directly athttp://localhost:8080:

dynamic_forwards:|  /api http://localhost:8080  /hook http://localhost:8080

Then all requests prefixed with the path/api and/hook will be forwarded tohttp://localhost:8080 and all the rest are forwarded to theforward_addr (http://localhost:3000).

Because the standard SSH protocol is used for tunneling, you may well just use the vanilla SSH client.

1. Go tohttp://example.com, authenticate with your SSO to obtain the token and URL (e.g.http://unknwon.example.com).
2. Launch the client by executing thessh -N -R 0::3000 example.com -p 2222 command:
   1. Enter the token as your password.
   2. Use the-v flag to turn on debug logging.
   3. Upon successful startup, you should see a log looks like:

      Allocated port 22487 for remote forward to :3000

3. Now visit the URL.

The project wouldn't be possible without readingfunction61/holepunch-server,function61/holepunch-client, andTCP/IP Port Forwarding.

This project is under the MIT License. See theLICENSE file for the full license text.