🦖 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.

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.

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! If you just installed Portzilla, you're already up to date. Otherwise, go to the Installed Apps page on your Cloudflare dashboard to check for updates. We're always adding new features and improvements. 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

This section is important if you're proxying to a page that loads static assets like images, stylesheets, and scripts.

When a website loads, it fetches these various resources from the local server. Because Portzilla is proxying traffic to this server, it needs to know which requests are initiated by the proxied service. Target Resources allows you to list the file paths of affiliated static asset requests.

Let's say you want to proxy a create-react-app project. After proxying to your app with Portzilla, navigate to the app's Route URL and open the Network tab of your browser's DevTools to identify assets that aren't loading. When you reload the page, you'll see one or more assets returning a 404 status code:

Requests In DevTools before setting Target Resources

Notice that the app initiates several requests for resources in the /static directory, a favicon.ico, and a manifest.json. These resources need to be whitelisted in Target Resources to load them correctly. We set up our Target Resources below:

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 proxy requests for favicon.ico, manifest.json and any files in subpaths of /static to our React app.

After saving Target Resources, our static assets load correctly:

Requests In DevTools after setting Target Resources

Consider the potential for collisions here in complex Portzilla configurations. If you're proxying more than one service that requests files from the /static directory, Portzilla will try to fetch resources from both services. This normally ensures the correct resource is retrieved.

However, if Portzilla encouters identical file paths, it will resolve the collision by loading the file the loads the fastest. A common cause for collisions is favicon.ico, which can lead to the incorrect favicon loading. To fix the collision, ensure common filenames like favicon.ico are unique for each of your proxied services.

WARNING

If you notice your proxied website doesn't look quite right, you probably need to add more entries to your Target 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

Error 525 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 all requests made to this route.

Advanced Options

Fetch Timeout

This is the number of seconds Portzilla will wait for a response from a service 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

Enable this if you want to temporarily disable Portzilla and all your routes without uninstalling it.

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.