Documentation

Expose Documentation

What is expose?

expose is a very simple application that does one thing. It gives a web server you have running locally a public URL which can then be accessed from any device that is connected to the Internet. Its a bit like a reverse proxy from the internet to your local machine and can handle all types of HTTP/HTTPS requests such as text, HTML, images, JavaScript and JSON.

It does not matter if your server is running a website, a web application, an API or another kind of service.

Normal network firewalls and routers won’t get in the way of expose, all requests are routed through the client app and it does not start its own server. So it should still work even if you are on a corporate network, VPN or local area network/LAN. You don’t need any special network config or networking knowledge.

It can handle any kind of web server including Nginx, Native NodeJS applications and servers running inside containerized environments like Docker, Kubernetes or a Virtual Machine.

Prerequisites

  • A machine running Linux, Mac OS X or Windows
  • expose is fairly lightweight, you don’t really need a very powerful machine to run it
  • A web server running locally over normal HTTP. This can be running natively or inside a containerized environment such as Docker, Kubernetes or a Virtual Machine as long as the configuration exposes the port. Examples include:
    • Nginx or Apache
    • Native NodeJS applications
    • A PHP, Java or other service running inside Docker that is configured to expose the web server port. If you can connect locally using your browser or API client, then the web server port is exposed.
    • It does not matter if this is a website, web application or API.

Getting started

Install expose

expose runs on Linux, Mac and Windows with native prebuilt executables. Follow the installation guide here to install for your OS.

Get a public URL for your local server

To get a public URL first start your server. Check the docs of your server if you aren’t sure how to do this. Take note of the port number you are running the server on.

Then run expose <port> where <port> is the port number. For example: If your server is running on port 80, run expose 80.

Here is the full command and example output:

$ expose 80
http://o0lktw.expose.sh is forwarding to localhost:80
https://o0lktw.expose.sh is forwarding to localhost:80

This is the most basic way to use expose and you now have two randomly generated URLs. One is plain HTTP, the other is secure HTTPS. Hit either of these URLs with any HTTP client such as a web browser, curl or an API client like Postman and the request will go to the server you have running locally. You should be able to use your server in the same way that you were using it locally with localhost or 127.0.0.1.

The HTTPS URL will work out of the box without any extra config. You do not need to buy a certificate or configure your server to use HTTPs, instead our own Lets Encrypt certificate will be used. Your server only needs to be running on plain HTTP.

These URLS can be used for - Demoing your work - Connecting a front end mobile app to a backend api you have running locally - Cross browser testing using real devices - HTTPS only features like Push Notifications and Progressive Web Applications (PWAs) with a local server

Each time you run expose in this way a new random URL will be generated. If you want a URL that does not change (for example, so you don’t need to reconfigure your application every time) read on.

Getting a URL that does not change

expose supports custom subdomains. So instead of <random string>.expose.sh you can have yourdomain.expose.sh.

This is a premium feature and its how we fund the service.

The cost is around $5 per month and up, about the same as you’d pay for your own cloud instance or VPS. First you’ll need to sign up here.

Once that is done, set your API key by running the command shown in your account which you’ll see after signing up or logging in. It looks similar to expose --set-api-key <your api key>.

After your API key is set, you can expose a web server with a custom subdomain by running expose <port> as <your subdomain>.expose.sh. For example if the subdomain you want to use is linuxhome.expose.sh and your server is running on port 80, run expose 80 as linuxhome.expose.sh.

Here is the full command with example output:

$ expose 80 as linuxhome.expose.sh
http://linuxhome.expose.sh is forwarding to localhost:80
https://linuxhome.expose.sh is forwarding to localhost:80

Cookbooks

- Learn webhooks in under an hour by example - Bitbucket webhooks - Gitlab webhooks - Github webhooks - Jenkins webhooks

Limits

expose connections expire after several hours and aren’t intended to be permanent. You shouldn’t have an expose URL as your production URL. Don’t use it for load testing or other high traffic workloads.

Different plans have different numbers of custom subdomains you can use simultaneously. The higher the plan, the more custom subdomains it comes with.

Conclusion

There isn’t really much to expose, its just a simple tool that gives you a public URL for a local web server and it doesn’t do any other fancy things. You can use these URLs for all kinds of things, but fundamentally thats all it does.

Hopefully you’ll find some ways to put these public URLs to use.