The pgrok is a multi-tenant HTTP 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 this as a bare-bone alternative to the ngrok's $65/user/month enterprise tier. Try 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 the Awesome 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:
- A domain name (e.g.
pgrok.dev
, this will be used as the example throughout this section). - A server (dedicated server, VPS) with a public IP address (e.g.
111.33.5.14
). - An SSO provider (e.g. Google, Okta, Keycloak) that allows you to create OIDC clients.
- A PostgreSQL server (bit.io, Cloud SQL, self-host).
Note
HTTPS for the web and proxy server is not required for this to work, while recommended if possible. Examples in the section all use HTTP.
- Add the following DNS records for your domain name:
A
record forpgrok.dev
to111.33.5.14
A
record for*.pgrok.dev
to111.33.5.14
- Create a
pgrokd.yml
file:external_url: "http://pgrok.dev" web: port: 3320 proxy: port: 3000 scheme: "http" domain: "pgrok.dev" sshd: port: 2222 database: host: "localhost" port: 5432 user: "REDACTED" password: "REDACTED" database: "pgrokd" identity_provider: type: "oidc" display_name: "Google" issuer: "https://accounts.google.com" client_id: "REDACTED" client_secret: "REDACTED" field_mapping: identifier: "email" display_name: "name" email: "email" # # The required domain name, "field_mapping.email" is required to set for this to work. # required_domain: "example.com"
- Download the latest version of the
pgrokd
archive from the Releases page. - Launch the
pgrokd
in background (systemd, screen, nohup).- By default,
pgrokd
expects thepgrokd.yml
is available in the working directory. Use--config
flag to specify a different path for the config file.
- By default,
- Alter your network security policy (if applicable) to allow inbound requests to port 2222 from
0.0.0.0/0
(anywhere). - Download and install Caddy 2 on your server, and use the following Caddyfile config:
http://pgrok.dev { reverse_proxy * localhost:3320 } http://*.pgrok.dev { reverse_proxy * localhost:3000 }
- Create a new OIDC client in your SSO with the Redirect URI to be
http://pgrok.dev/-/oidc/callback
.
- Go to http://pgrok.dev, authenticate with your SSO to obtain the token and URL (e.g.
http://unknwon.pgrok.dev
). - Download the latest version of the
pgrok
:- For Homebrew:
brew install pgrok/tap/pgrok
- For others, download the archive from the Releases page.
- For Homebrew:
- Initialize a
pgrok.yml
file with the following command (assuming you want to forward requests tohttp://localhost:3000
):By default, the config file is created under the home directory (pgrok init --remote-addr pgrok.dev:2222 --forward-addr http://localhost:3000 --token {YOUR_TOKEN}
~/.pgrok/pgrok.yml
). Use--config
flag to specify a different path for the config file. - Launch the client by executing the
pgrok
orpgrok http
command.- By default,
pgrok
expects thepgrok.yml
is available 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:
YYYY-MM-DD 12:34:56 INFO Tunneling connection established remote=pgrok.dev:2222
- By default,
- Now visit the URL.
Following config options can be override through CLI flags:
--remote-addr
->remote_addr
--forward-addr
->forward_addr
--token
->token
As a special case, the first argument of the pgrok http
can be used to specify forward address, e.g.
pgrok http 8080
In addition to traditional request forwarding to a single address, pgrok
can be configured to have dynamic forward rules.
For example, if your local frontend is running at http://localhost:3000
but some gRPC endpoints need talk to the backend directly at http://localhost:8080
:
dynamic_forwards: |
/api http://localhost:8080
/hook http://localhost:8080
Then all request prefixed with the path /api
and /hook
will be forwarded to http://localhost:8080
and all the rest are forwarded to the forward_addr
(http://localhost:3000
).
Because the standard SSH protocol is used for tunneling, you may well just use the vanilla SSH client.
- Go to http://pgrok.dev, authenticate with your SSO to obtain the token and URL (e.g.
http://unknwon.pgrok.dev
). - Launch the client by executing the
ssh -N -R 0::3000 pgrok.dev -p 2222
command:- Enter the token as your password.
- Use the
-v
flag to turn on debug logging. - Upon successful startup, you should see a log looks like:
Allocated port 22487 for remote forward to :3000
- Now visit the URL.
- The logo is from flaticon.com.
- The project wouldn't be possible without reading function61/holepunch-server, function61/holepunch-client, and TCP/IP Port Forwarding.
This project is under the MIT License. See the LICENSE file for the full license text.