☁️ Learn how to use ngrok
so that
you can share
a Web App/Site running on your "localhost"
with anyone online!
You are working on a Web App/Site on your localhost
,
but it's "not yet ready" to be "deployed"
Note: once you are ready to make your App/MVP "official", you should consider using Heroku as it does not require you to have your
localhost
running (and it has good logging, "monitoring", "free tier", etc.).
See: github.com/dwyl/learn-heroku
The official description on the website https://ngrok.com/product is:
"
ngrok
exposeslocal
servers behind NATs and firewalls to thepublic
internet over secure tunnels."
In plain (beginner friendly) English:
ngrok
is a small piece of software that lets you run a web application
on yourlocal
computer and (securely) share it with the world on apublic
address ("URL").
Anyone working on a Web App/Site
and needs a quick/easy way to show or test it
without "deploying" it.
e.g: you are actively developing something
and deploying it to
Heroku
would be too time consuming.
A great use-case is when you are in "development mode",
you have "live-reloading" enabled on your locahost
and you want any changes you make on your to be reflected
a mobile device without having to re-deploy.
Often you will be on a network with strict firewall rules (blocked TCP ports) that do not allow you to share your app with your Mobile device! e.g: in Coffee Shops, Libraries or "Corporate" Networks.
In these cases ngrok
is a great choice!
Avoid using ngrok
when your app
is being actively used by people.
i.e: once your "MVP" is ready to be tested by "real users",
deploy it somewhere that is not your localhost
e.g: Heroku
The official "getting started" guide is: https://dashboard.ngrok.com/get-started Is a good place to start, however we have "condensed" it down into just 4 steps!
First step on our quest is to download ngrok
from the website:
https://ngrok.com/download
If you use a Mac computer (and "homebrew") there's an easy way; Run the following command in your terminal:
brew cask install ngrok
Once you have successfully downloaded and installed ngrok
.
If you have not already authenticated with ngrok
visit: https://dashboard.ngrok.com/user/login
We use our GitHub account to authenticate with ngrok
because they only asks for basic access:
Once authenticated, you should see a "Dashboard": https://dashboard.ngrok.com/get-started
If you scroll down you will see a section entitled:
"Connect your account"
e.g:
Copy-pasge and run the command in your terminal
(including your unique authtoken
,
which you should not share BTW!)
./ngrok authtoken 56hth5o3bbkewDmHSZEHQ_39VJe8koVu
Don't worry, this example is not a "valid" token, it's just for demo purposes.
if you see an error:
-bash: ./ngrok: No such file or directory
simply remove the ./
in front of the ngrok
command:
Thanks to: https://stackoverflow.com/questions/30188582/ngrok-command-not-found/43492639
Now it's time to run your app on your localhost
.
Run which ever command you need (e.g: npm start
or mix phx.server
)
to start your app.
Make a note of the TCP Port your app is running on for step 4 below.
If you don't already have an "App" to try/test ngrok
,
you can simply "clone" this repository and try the "demo" App!
Copy-paste and run the following command:
git clone https://github.com/dwyl/learn-ngrok.git && cd learn-ngrok && npm install
(note: it take a few seconds for that command to run because it's installing the "live-server" dependency for running the app, be patient ...)
In your Terminal window you should see something like this:
Once the command has run it will start the "app"
and open it in your default
web browser. e.g:
Create the ngrok
"tunnel" to your app
by running the following command
in a new
terminal window
(different from the one where your app is running):
./ngrok http 4000
or (on Mac OSX):
ngrok http 4000
you should now see something similar to this:
This confirms that the ngrok
forwarding the given URL
to your locahost
on TCP Port 4000
.
In our case the ngrok
URL is https://f00ead01.ngrok.io
but yours will be a different random string as the sub-domain.
Open your Web Browser and visit: https://f00ead01.ngrok.io
Voilà! Your App on the public
Internet!
(not that you had any doubt it would work ...)
To Quit ngrok
simply use the Ctrl+C
command.
Note: if you
quit
ngrok
the URL of your app will change. That's why the URL in the GIF below is different from this one ... if you want a fixed URL, you will need to pay for it.
Open the ngrok
"inspector" http://localhost:4040
a new tab or browser window:
If you make a simple change in your App,
you should see it update in the browser!
(the "demo" App has "live reloading"
if yours does not, simple refresh the browser window.)
e.g:
That's it!
Obviously
ngrok
has many more "advanced" features, we encourage you to read the docs if you need something specific: https://ngrok.com/docs
If you have any questions, get "stuck" or want a more "advanced example", please open an issue: https://github.com/dwyl/learn-ngrok/issues