Guide to Configuring Ngrok Reverse Proxy Service in ServBay

Ngrok is a powerful and secure tunneling tool based on reverse proxy technology. It can penetrate firewalls and NAT, mapping services running on your local machine to a public domain name. This guide provides a detailed walkthrough on how to integrate and configure Ngrok with the ServBay local development environment, enabling internet access to local web services, APIs, or other applications—ideal for remote demos, team collaboration, or third-party callback testing.

Technical Principle

Ngrok works by establishing an encrypted tunnel between your local machine and Ngrok’s servers. When an external user accesses the publicly assigned Ngrok domain, their request first reaches Ngrok’s server, which then securely forwards it through the tunnel to the corresponding service running locally in ServBay. This means you can expose your services online even if your local machine lacks a public IP or is behind a firewall. In ServBay, it allows you to instantly share locally hosted websites, backend APIs, or any HTTP/HTTPS-based service with the outside world for testing and demonstration purposes.

Prerequisites

Before configuring Ngrok, please ensure you have completed the following:

1. ServBay is Installed and Running: Make sure the ServBay application is correctly installed and the web service you wish to expose (for example, a website) is configured and running in ServBay. You can check and manage local website configurations in ServBay’s "Websites" panel.
2. Ngrok Client Installation: Deploy the Ngrok CLI tool using these steps:
   1. Visit the Ngrok official download page to obtain the installer corresponding to your OS.
   2. After downloading, extract the archive. Move or copy the extracted ngrok executable to a directory included in your system PATH (such as /usr/local/bin on macOS) so you can run ngrok from any terminal.

      # Example for macOS ARM64 architecture
      sudo unzip ~/Downloads/ngrok-v3-stable-darwin-arm64.zip -d /usr/local/bin

   3. Verify a successful installation by running the ngrok version command to display the version number:

      ngrok version
      # Example output: ngrok version 3.5.0

3. Ngrok Account (Optional but Recommended): Having a Ngrok account (free or paid) makes it easier to manage tunnels and use advanced features like static domains. Register at the Ngrok official website and obtain your auth token (ngrok config add-authtoken <YOUR_AUTH_TOKEN>), which removes tunnel session time limits and grants access to more functionality.
4. Configured Local Website: You should have at least one local website set up in ServBay that you want to expose, such as with the domain servbay.local or yourproject.servbay.demo for local access.

Tunnel Configuration in Practice

Key Parameter Explanation

The standard command structure for service mapping is as follows:

ngrok http --domain=<NGROK_DOMAIN> <LOCAL_ENDPOINT> \
  --request-header-add='host: <VIRTUAL_HOST>'

Parameter	Description
http	Establishes an HTTP protocol-based tunnel. Ngrok will process incoming HTTP/HTTPS requests.
--domain <NGROK_DOMAIN>	Specifies the static domain assigned by Ngrok (replace with your actual domain configured or assigned in the Ngrok Dashboard). This is usually not needed for the free plan, as Ngrok will automatically allocate a random subdomain.
<LOCAL_ENDPOINT>	The address of your ServBay local service. For ServBay virtual hosts, this is usually the local access domain (e.g., https://servbay.local). It can also be http://localhost:port.
--request-header-add='host: <VIRTUAL_HOST>'	[Important] Rewrites the Host header. ServBay distinguishes different local sites (virtual hosts) using the HTTP Host header. This parameter modifies the incoming Host header to your configured local domain (e.g., servbay.local) to ensure ServBay routes the request to the correct site.

Configuration Example

Suppose you have a local website in ServBay accessible at servbay.local, and you want to expose it publicly via Ngrok. If you are on Ngrok’s free plan, you can map the local address directly:

# Map the local ServBay site servbay.local to a random Ngrok-assigned public domain
ngrok http https://servbay.local --request-header-add='host: servbay.local'

If you have configured a static domain in the Ngrok Dashboard, such as your-servbay-demo.ngrok-free.app or a custom paid domain, use the --domain parameter:

# Map the local ServBay site servbay.local to a specified Ngrok domain
ngrok http --domain=your-servbay-demo.ngrok-free.app https://servbay.local --request-header-add='host: servbay.local'

Once the command executes successfully, the Ngrok client will display tunnel status in your terminal, including the assigned public address (e.g., https://xxxx.ngrok-free.app or your configured domain) and a local monitoring dashboard address (typically http://127.0.0.1:4040).

Service Verification

After setting up and starting the Ngrok tunnel, follow these steps to verify public access:

1. Obtain the Public URL: In the Ngrok client terminal window, find the Forwarding line, and note the https:// public URL.
2. Browser Access: From any networked device, use a browser to visit the Ngrok public URL you obtained (e.g., https://cunning-lacewing-fresh.ngrok-free.app or your static domain).
3. Verify Results:
   • Confirm your locally hosted ServBay website loads correctly in the browser.
   • Check the browser's address bar for a secure HTTPS connection symbol—Ngrok provides a valid SSL certificate for tunnels by default.
   • You can view request logs and traffic stats via the Ngrok client terminal or its web interface (usually http://127.0.0.1:4040), ensuring requests reach and are served by ServBay.

Illustration: Successfully accessing an Ngrok tunnel via web browser

Advanced Tips and Considerations

1. Domain Management:
   • With the free Ngrok plan, tunnels are assigned a random .ngrok-free.app subdomain with session time limits.
   • Registering a Ngrok account and configuring a static domain in the Ngrok Dashboard prevents public URL changes each time a tunnel is started.
   • Paid plans allow you to bind your own top-level domain and provide greater bandwidth, more concurrent tunnels, and enhanced features.
2. Mapping Multiple Services: If you need to expose multiple different local services or ports in ServBay to the internet, you can run multiple Ngrok tunnel processes or define/manage them with the Ngrok config file (usually at ~/.config/ngrok/ngrok.yml). For example, mapping both a ServBay site and another service:

   # Map servbay.local in ServBay (assuming HTTPS 443, routed by Host header)
   ngrok http --domain=servbay-website.ngrok-free.app https://servbay.local --request-header-add='host: servbay.local'
   
   # In another terminal or via the config file, map a local Node.js app on port 3000
   ngrok http --domain=nodejs-api.ngrok-free.app http://localhost:3000

   Note: For ServBay virtual hosts, it is advised to use https://[local-domain] with --request-header-add instead of directly mapping ServBay’s 80/443 ports, as ServBay handles all virtual host requests on those ports.
3. Diagnostic Commands:
   • ngrok config check: Validates syntax of your Ngrok config file (usually ~/.config/ngrok/ngrok.yml).
   • ngrok logs: View Ngrok client detailed log output in real time, very useful for diagnosing connectivity or routing issues.
4. Security: Exposing local services online involves risks. Ensure your exposed services are secure and run Ngrok tunnels only when necessary. Paid Ngrok plans add IP whitelisting and access restriction features for more security control.

Troubleshooting

Symptom	Solution
Connection times out or page fails to load	Check whether the ServBay site is running and accessible via your local domain (for example, visit https://servbay.local in your browser). Confirm the ServBay web server (such as Caddy or Nginx) is working. Make sure your firewall allows Ngrok’s network connections.
HTTPS certificate error (browser warning)	Ngrok provides valid HTTPS certificates for public domains by default. If you see certificate errors when accessing the Ngrok public domain, it's likely an Ngrok tunnel or network issue, not related to ServBay. Ensure you are accessing the Ngrok-assigned https:// address. If errors occur on local domain access, check your ServBay SSL setup.
Intermittent disconnection or slow speed	Check the stability of your internet connection. Network instability may interrupt tunnels. Prefer wired connections when possible. For high-stability needs, consider Ngrok’s paid plans for more reliable infrastructure and greater bandwidth.
Landing on ServBay’s default page instead of your website	Confirm that the <LOCAL_ENDPOINT> in the ngrok http command is correct and the <VIRTUAL_HOST> in --request-header-add='host: <VIRTUAL_HOST>' is set to your ServBay local site domain. This is key to having ServBay route requests to the correct website.

Frequently Asked Questions (FAQ)

• Q: Can I map ServBay’s database services?

  A: Ngrok is mainly intended for HTTP/HTTPS tunneling. While it also supports TCP tunnels for services like databases, this lies outside the scope of this HTTP-focused guide. Directly exposing your local database is not recommended due to security risks. For remote database access, consider SSH tunneling or other secure alternatives.

• Q: Will the public domain name change every time I start Ngrok?

  A: On the free Ngrok plan, the assigned .ngrok-free.app subdomain is usually random. To get a fixed public URL, register a Ngrok account and configure it in the Dashboard or upgrade to a paid plan.

• Q: Will using Ngrok affect my local ServBay performance?

  A: Ngrok introduces some network latency as requests are relayed through its servers. For development, testing, and demos, this is typically acceptable. Your local ServBay service speed depends on your computer's performance and the efficiency of your site/application.

Conclusion

By integrating Ngrok, ServBay users can easily and securely share their local web development work online. There’s no need for complex networking setup, making it especially suitable for remote collaboration, client demos, mobile or third-party integration testing, etc. Ngrok offers real-time traffic monitoring and robust security options (some features require a paid subscription). For mission-critical scenarios or when static domains are needed, consider Ngrok's paid services for a more stable and feature-rich experience.