🦖 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.
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.
REQUIRED
Network Policies 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
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.
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.

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
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.
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.
My
POST
requests are registering asGET
requests.- Cloudflare's Always Use HTTPS feature rejects insecure POST requests that use
http:
instead ofhttps:
. If possible, modify your request to usehttps:
or disable Always Use HTTPS.
- Cloudflare's Always Use HTTPS feature rejects insecure POST requests that use
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, yourTarget Location
should not contain the www subdomain if your site appears at https://yoursite.com.
I'm encountering a SSL Handshake Failed error when I proxy to a service.
- If your domain is secured with https:, enable
Use HTTP
if your target service uses http:
- If your domain is secured with https:, enable
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.
- Route Name
- Route URL
- Target Port
- Target Location
- Target Redirect
- Redirect Status Code
- Target Resources
- Request Headers
- Custom Error Page
- Use HTTP
- Single Page App Mode
- Enable Cache
These Advanced Options are also available:
Route Configuration
REQUIRED
Route Name 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 | 🎉 |
REQUIRED
Route URL 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
.
OPTIONAL
Target Port 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.
OPTIONAL
Target Location 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.
OPTIONAL
Target Redirect All traffic from Route URL
will be redirected to this location.
OPTIONAL
Redirect Status Code Traffic from Route URL
will be redirected with this 300-level status code.
OPTIONAL
Target Resources 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:
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:
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
.
OPTIONAL
Request Headers 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
OPTIONAL
Custom Error Page 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
.
OPTIONAL
Use HTTP 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.
OPTIONAL
Single Page App Mode 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.
OPTIONAL
Enable Cache 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.
Edgy →