🦖 Portzilla

The Skinny

Proxy traffic from any URL on your domain to a service listening on another port. You can even send headers along with each request.

Say you want to connect your docs server to your website.

Use Portzilla to proxy traffic from docs.yoursite.com to your server listening on port 4080.

curl docs.yoursite.com → yoursite.com:4080

You would normally need NGINX or Apache for this. Instead, Portzilla proxies your traffic without all of the complex configuration and overhead.

graph LR; A[Browser] --> |request to
docs.yoursite.com| B{Portzilla} style B fill:#5EE5FB,stroke:#333,stroke-width:3px B --> |response| A B --> DD(GET yoursite.com:4080) style DD fill:#FFF,stroke:#333,stroke-width:1px DD --> B

How to Install

Powered by Cloudflare

Portzilla is powered by Cloudflare. If you're already using Cloudflare, click here to install Portzilla.

TIP

Cloudflare offers DDoS protection, a global CDN, SSL certificates, and a lot more cool stuff for free. You should probably use it.

Network Policies
REQUIRED

Services that are proxied by Portzilla must accept incoming http(s) traffic. You may need to adjust your network policy to ensure each proxied port is accepting traffic. Refer to your network policy documentation to learn how to open ports on your platform.

WARNING

If you open a port on your Cloudflare-enabled site, your service won't automatically respond on http://www.yoursite.com:<PORT>. Portzilla does this for you.

To test your service, install Portzilla and set up a route to the port its listening on. If you get an Error Page when your visit the Route URL, you probably need to tweak your network policy.

Getting Started

After installation, activate Portzilla by clicking the link in the email we sent you.

Next, visit our tutorials to get started with various platforms. Learn more about common Portzilla questions and troubleshooting tips:

Have a Twitter account? Extend your free trial!

Visit portzilla.networkchimp.com/extend for more details.

Tutorials

Check out these tutorials to see Portzilla in action:

FAQ

The following sections summarize the most common connectivity issues that users encounter with services proxied by Portzilla:

  • Before establishing a connection
  • After establishing a connection

Before connecting

  1. Help! I cannot connect to my service with Portzilla.

    • First, ensure you're on the latest version! We're always adding new features and improvements new versions. If you still see an issue after reading this section, let us know and we'll take a look as soon as possible!

    • Confirm that your API is open to the internet by ensuring you can make requests to it directly. For example, if your API is on port 3000 on an EC2 instance, your api should respond to:

curl -I <your-subdomain>.amazonaws.com:3000

# If you don't get a response, open the port to http(s) traffic accordingly.
  1. I can communicate with my service, but I still can't connect to it with Portzilla!

    • If you're setting up a port proxy, do you have a DNS record pointing at your service? Ensure your CNAME or A record correctly maps your service to a valid subdomain.
portzilla dns configuration

SANITY CHECK

Is your service running on the machine you think it is? Is it possible the service is running on a different machine?

After connecting

  1. I updated my Portzilla configuration but my website still reflects the old configuration.

    • Cloudflare may still be propagating your changes. Usually, this only takes a few seconds, but it can occasionally take a few minutes for changes to take effect.
    • Your browser may be caching pages based on previous configurations. This often happens with redirects and resources. Try opening your website in a private (or incognito) tab to avoid caching issues.
  2. My Javascript or Single Page App is not behaving correctly with Portzilla.

    • Enable Single Page App Mode.

    • If your app is proxied using a subpath like yoursite.com/my-app, ensure your app's base URL is configured correctly. Visit this answer for more information.

    • If you're experiencing 404's when fetching static files, ensure your Target Resources are set.

  3. My POST requests are registering as GET requests.

    • Cloudflare's Always Use HTTPS feature rejects insecure POST requests that use http: instead of https:. If possible, modify your request to use https: or disable Always Use HTTPS.
  4. I am getting redirected to the website or location that I want to proxy!

    • When troubleshooting this, ensure you're using a new private (or incognito) window after each configuration update.

    • You may be encoutering a protocol upgrade redirect if your proxy target uses https:. Try changing the protocol of your Target Location from http: to https:.

    • If you are proxying to another Target Location on the same domain, ensure it follows the same subdomain pattern. For example, your Target Location should not contain the www subdomain if your site appears at https://yoursite.com.

  5. I'm encountering a SSL Handshake Failed error when I proxy to a service.

    portzilla dns configuration
    • If your domain is secured with https:, enable Use HTTP if your target service uses http:

Configuration

Portzilla is easy to set up once you get your ports open! The instructions on the installation page are fairly self explanatory, but we'll go into a little more detail here.

The following Route Configuration is available for each route Portzilla should handle.

These Advanced Options are also available:

Route Configuration

Route Name
REQUIRED

Give your route a name to remember it by. Here's some names if you're lacking inspiration.

Route Name Result
muh route 🤮
docs to vuepress server 🎉
(blank) 🤮
swagger ui 🎉

Route URL
REQUIRED

Traffic to this URL will be proxied to Target Port or Target Location.

This can be any URL on your domain and can include subdomains. It is important that a full URL is specified here. Portzilla won't like it if you supply a path like /store. It requires a URL like yoursite.com/store to work right. Here's some more examples.

Route URL Result
/sad/path 🤮
yoursite.com/cool-beans 🎉
blog.yoursite.com 🎉

Portzilla automatically proxies all requests made to any subpath of Route URL. In the table above, traffic to blog.yoursite.com/topics will be proxied.

Portzilla treats the root domain and the www subdomain identically.

Route URL Proxied subdomains
yoursite.com yoursite.com and www.yoursite.com
www.yoursite.com yoursite.com and www.yoursite.com

You can achieve the same behavior with either Route URL.

Target Port
OPTIONAL

All traffic from Route URL and any of its subpaths will be proxied to the service running on this port. Any non-reserved Target Port is allowed.

Ensure your service running here is open to internet traffic. If you encounter an SSL Handshake Failed error, enable the Use HTTP option.

Target Location
OPTIONAL

All traffic from Route URL and any of its subpaths will be proxied to the service running at this web address.

Ensure the correct protocol is set to avoid SSL Handshake Failed errors.

Target Redirect
OPTIONAL

All traffic from Route URL will be redirected to this location.

Redirect Status Code
OPTIONAL

Traffic from Route URL will be redirected with this 300-level status code.

Target Resources
OPTIONAL

If you're proxying to a static page or framework like a React site or Ghost blog, you'll definitely want to read this section.

When a service loads, it might fetch various resources like scripts, images, and stylesheets from a local server. You'll need to whitelist those Resources here.

For example, let's say you want to show off your brand new create-react-app project to the world. Find its resources in the Network tab of your browser's DevTools.

Resources In DevTools

Upon inspection, you'll notice that localhost:3000 serves several resources under the /static directory, a favicon.ico and a manifest.json. These need to be whitelisted in Target Resources to fetch correctly.

Target Resources:

www.yoursite.com/static
www.yoursite.com/favicon.ico
www.yoursite.com/manifest.json

Notice that full URL's like www.yoursite.com/static are required here. Portzilla won't work if you only specify the path.

The above configuration tells Portzilla to forward requests for favicon.ico, manifest.json and any files in /static and any subpath of /static.

Consider the potential for collisions here. With multiple Portzilla configurations, you may have two services with resources in the /static directory, Portzilla will try to fetch requested resources from each one. This normally ensures the correct resource is retrieved. However, if Portzilla encouters identical file paths, it will load whichever file is fetched first. For example, you'll need unique names for common files like favicon.ico because there is no way to avoid collisions between the favicons of a proxied service and your main website.

WARNING

If you notice your proxied website doesn't look quite right, you probably need to whitelist more resources.

Request Headers
OPTIONAL

You can specify any number of headers to pass along with requests sent to the service running on Target Port. Each header should be new-line separated. In other words, hit enter after each header you type. Here's what request headers might look like in a Portzilla configuration.

X-Forwarded-From: blog
Some-Other-Header: hey lol
athirdheader: you get the point

Custom Error Page
OPTIONAL

An HTML template to show if your service on Target Port is unresponsive. Portzilla will render it's default Error Page unless you specify your own template in Custom Error Page.

The Error Page will appear after the number of seconds configured in Fetch Timeout.

TIP

Enable Advanced Options > Debug Mode to display Portzilla's Debug Page instead. This is useful if you're having trouble connecting to your service on Target Port.

Use HTTP
OPTIONAL

If traffic to Route URL is secured, proxied requests will also be secured. Enable this to use http instead.

TIP

SSL Handshake Failed is a common issue encoutered when your domain is secured but the proxied service is insecure. Enable Use HTTP to fix the error.

Single Page App Mode
OPTIONAL

When routing to a Single Page App like React, Vue, Angular, etc...etc...etc., enable this to ensure that subroutes are handled appropriately.

TIP

Javascript frameworks often have a base parameter that should be set if the app is running on a subpath. For example, if you are running Vuepress on www.yoursite.com/docs, set base: '/docs' in your config.js. Refer to your framework's documentation for specific instructions.

Enable Cache
OPTIONAL

Pages that hit Portzilla are not cached by default. This enables caching of any request made to this route.

Advanced Options

Fetch Timeout

This is the number of seconds Portzilla will wait for a response from the service listening on Target Port before giving up and rendering the Error Page. The default value is 5 seconds.

TIP

If your service takes a while to spin up or is otherwise slow, increase Fetch Timeout.

Disable Portzilla

If you want to temporarily disable Portzilla and all your routes, this is your option.

Debug Mode

This is useful if you're having trouble connecting to your service on Target Port. When Debug Mode is active, the Portzilla Debug Page will appear after a failed request.

TIP

In Debug Mode, Fetch Timeout is set very high so the request will complete.

Attributions

The Custom Error Page logo was designed by Kiranshastry at FlatIcon.