Setting Up Reverse Proxies in ServBay: Map Intranet or Remote Websites to Your Local Environment for Development and Debugging

ServBay is a local web development environment designed specifically for macOS, integrating multi-language runtimes including PHP, Node.js, Python, Go, Java, as well as databases such as MySQL, PostgreSQL, MongoDB, and Redis. Beyond directly hosting local code projects, ServBay offers a powerful reverse proxy feature. With reverse proxying, you can easily map web sites hosted on internal networks, virtual machines, containers, or even remote servers into your local ServBay environment, simplifying development, debugging, and access workflows.

This article provides a step-by-step guide on how to set up reverse proxies in ServBay so you can proxy sites from the intranet or other accessible addresses to your local environment for unified management and efficient development/debugging.

Overview

A reverse proxy server receives requests from clients (e.g., your browser) and forwards them to one or more backend servers (in this case, the intranet or remote sites you want to proxy). ServBay accomplishes this using its built-in web server—Caddy or Nginx.

In local development scenarios, the main advantages of setting up a reverse proxy are:

• Unified Access Point: Access all internal or external resources through local ServBay domains, without memorizing complicated IP addresses and ports.
• Simplified SSL Configuration: Take advantage of ServBay's SSL management features (like ServBay CA or ACME) to provide HTTPS access to proxied websites, even if the backend only supports HTTP.
• Local Debugging: Easily debug remote or intranet web applications in your local browser environment.
• Bypass Network Restrictions: In some cases, you can conveniently access company intranet or restricted network resources from your local environment (provided your ServBay machine can access the target address).

Prerequisites

Before configuring a reverse proxy, make sure that:

1. ServBay is Installed and Running: Ensure the ServBay application is correctly installed and running on your macOS system.
2. Target Website is Accessible: The intranet or remote website you wish to proxy is running normally, and your macOS machine (where ServBay runs) can directly access the site's IP/domain and port over the network. For example, if the target is 192.168.1.100:8080, make sure your macOS can ping 192.168.1.100 and access 192.168.1.100:8080.

Steps to Add a Reverse Proxy Website

Follow these detailed steps to configure a reverse proxy site in ServBay:

Step 1: Open ServBay Management Interface

Locate the ServBay icon in your macOS Applications folder and double-click it to launch the application.

Step 2: Navigate to Website Management

Once ServBay launches, you'll see the main dashboard. In the navigation panel on the left, click on Websites. This brings you to ServBay’s website management page, where you can manage all locally hosted and reverse proxy sites.

Step 3: Add a New Website

At the bottom of the website management page, find and click the + button. This will expand a new form in the right pane for configuring your new website.

Step 4: Configure Reverse Proxy Settings

In the new website form, fill in the key information to define the reverse proxy’s behavior:

1. Name: Assign an easy-to-recognize name to your reverse proxy site. For example: Internal Backend Proxy.
2. Domain: Enter the domain through which you want to access the proxied website locally. For example: backend.servbay.demo or proxy.to.local. ServBay will typically auto-add the entered local development domain to your system's hosts file, mapping it to 127.0.0.1 or ::1.
3. Protocol: Select which protocol the site should support. Usually, HTTP/HTTPS is chosen to support both protocols. ServBay will handle SSL automatically per your configuration.
4. SSL Certificate Request Method:
   • ServBay CA (Recommended for local development): This option lets ServBay use its built-in Certificate Authority (CA) to automatically generate and manage SSL certificates for your domain. It's convenient, but you must trust the ServBay CA root certificate in your browser/system to avoid warnings.
   • ACME (Let's Encrypt): Choose this if you have a public domain name that can be accessed via the Internet, allowing you to obtain a free SSL certificate from Let's Encrypt.
   • Manual: If you already have existing SSL certificate files (.crt, .key, .ca-bundle), select this to upload and configure manually. For local development and proxying intranet resources, it’s strongly recommended to choose ServBay CA.
5. Website Type: Choose Reverse Proxy. This is essential for enabling proxy functionality.
6. Proxy Target: Enter the complete URL or IP:Port of the internal or remote site you wish to proxy.
   • Example 1 (IP:Port): 192.168.1.100:8080
   • Example 2 (Protocol with URL): http://192.168.1.100:8080
   • Example 3 (Intranet hostname): backend.internal:8443 (assuming ServBay can resolve this name)
   • Example 4 (Remote URL): https://api.example.com Make sure the address entered here is directly accessible from your ServBay machine.

Step 5: Complete and Save Configuration

After entering all the required details, click the Add button at the bottom of the form. ServBay will automatically save your configuration and generate the corresponding reverse proxy rules within its web server (Caddy or Nginx).

Once saved successfully, your new reverse proxy site will appear in the website list.

Step 6: Access the Reverse Proxy Website

Once configuration is complete, simply enter the domain you set up in Step 4 (such as proxy.to.local or backend.servbay.demo) into your browser to access your proxied intranet or remote site.

If you use ServBay CA and chose HTTPS, you might need to handle an initial certificate warning in your browser (if the ServBay CA root certificate hasn't yet been trusted).

Step 7: Website Quick Actions

ServBay provides handy quick action buttons for each website to help you manage them easily:

1. Open Site Root in IDE: For reverse proxy sites, this may be less relevant as there’s no local root directory.
2. Open Website in Browser: Quickly open the website in your default browser.
3. View Website Logs: Check access and error logs from the ServBay web server (Caddy/Nginx) for this site—essential for debugging.
4. Pause/Enable Website: Temporarily enable or disable this reverse proxy configuration.
5. Delete Website: Remove this reverse proxy configuration from ServBay.

Frequently Asked Questions (FAQ) & Solutions

Q: Website is inaccessible; browser shows an error.

• Check ServBay Status: Ensure ServBay itself is running and that its web server (Caddy/Nginx) has started.
• Check Domain Resolution: Confirm you entered the domain correctly in your browser and that it resolves to your local ServBay IP (ServBay typically auto-modifies the hosts file, but you can check manually).
• View ServBay Site Logs: Use the "View Logs" button in the website list to inspect ServBay’s web server logs. These record client request details, ServBay attempts to connect to proxy targets, and any errors—this is the most direct way to troubleshoot.
• Check Firewall/Security Software: Make sure your macOS firewall or any security software isn’t blocking ServBay from listening on ports 80 or 443, or preventing ServBay from connecting to your proxy target.

Q: ServBay machine can access the proxy target but accessing via the ServBay domain in the browser fails.

• Check Proxy Target Format: Ensure the "Proxy Target" address in ServBay is formatted correctly and that your ServBay machine really can access the target site directly at that address. Try using curl [proxy target address] in a terminal.
• Back-end Server Config: Some back-end servers check the request Host header. By default, ServBay forwards the original Host header from the client. If the back-end requires a specific Host (such as an intranet domain) while you access through a different domain in ServBay, it may cause issues. In ServBay’s advanced settings, you can adjust forwarded headers (which may require manual editing of Caddyfile or Nginx config, beyond the basic UI).
• Check Target Server Firewall: Even if ServBay can access the target IP/port, the target server's firewall might only allow connections from certain IP ranges (e.g., the intranet). Make sure the target allows connections from your ServBay machine’s IP.

Q: Certificate warnings appear when accessing the reverse proxy website via HTTPS.

• Using ServBay CA: If you chose ServBay CA, this is expected behavior as ServBay CA is a private Certificate Authority not trusted by browsers by default. You’ll need to manually trust the ServBay CA root certificate in your operating system or browser, which can be installed from ServBay’s settings.
• Using ACME (Let’s Encrypt): Make sure your domain resolves to the ServBay machine’s IP and that you’ve requested an ACME certificate via ServBay’s SSL management platform. Check ServBay’s logs for detailed errors during the ACME process.

Q: How to proxy to targets that require specific headers or cookies?

The basic reverse proxy setup in ServBay generally forwards most client request information. For more complex scenarios—such as adding custom headers, modifying response headers, handling specific cookies, or path rewrites—you need to access ServBay’s advanced settings and manually edit the underlying Caddyfile or Nginx config to add more refined reverse proxy rules. This requires some familiarity with the configuration syntax of Caddy or Nginx.

Conclusion

With ServBay’s reverse proxy feature, you can easily integrate web sites from intranets, virtual machines, containers, or remote servers into your local development environment. This not only provides a unified, convenient access point but also streamlines local debugging and SSL configuration. By following the steps in this guide, you can quickly set up and start using reverse proxy websites. Leveraging ServBay’s powerful logging and troubleshooting features, you can ensure stable operation and significantly boost your development productivity.