🦖 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.
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
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
POSTrequests are registering asGETrequests.- 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 Locationfrom http: to https:.If you are proxying to another
Target Locationon the same domain, ensure it follows the same subdomain pattern. For example, yourTarget Locationshould 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 HTTPif 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
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:
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.
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.
Edgy →