Adding and Configuring Docker Container-Based Websites in ServBay

ServBay is a local web development environment tailor-made for macOS, supporting diverse languages and tech stacks. In addition to running websites directly using ServBay’s built-in packages (like PHP, Node.js, Python, Go, Java, databases, etc.), you can also utilize Docker containers to run and manage your websites or services. This approach delivers exceptional flexibility, environment isolation, and consistency—especially valuable for projects with specific environment or dependency requirements.

This guide provides step-by-step instructions on how to add a website powered by a Docker container to ServBay and integrate it into your local development workflow with ServBay’s reverse proxy feature.

Overview

By setting up ServBay as a reverse proxy, you can forward requests for specific domain names to services running inside Docker containers on particular ports. ServBay handles incoming traffic (such as HTTPS certificates, domain resolution, etc.), while the Docker container focuses on running your application. This model combines ServBay’s user-friendly management interface with the robust containerization of Docker.

The following steps will guide you through the entire process of adding and configuring a Docker-driven website within ServBay.

Prerequisites

Before proceeding, ensure you meet the following requirements:

1. ServBay is installed and running: You have successfully installed and launched ServBay on your macOS system.
2. Docker is installed and running: Docker Desktop or another Docker environment is installed on your macOS, and the Docker service is active.
3. Docker images and containers are ready: You have built or pulled the Docker image containing your website or application, and you're able to start a container from this image.

Detailed Steps to Add a Website

Step 1: Prepare and Run the Docker Container

First, make sure your Docker container is running, and the internal service (such as the web server) is listening on a port that is exposed to your host (macOS) through Docker's port mapping feature.

For example, if you have a simple Nginx container where Nginx listens internally on port 80, you can use the following command to map port 8080 on your host to port 80 in the container:

docker run -d --name my-nginx-servbay -p 8080:80 nginx

In this example, the Nginx service inside the Docker container my-nginx-servbay listens on port 80, but the -p 8080:80 flag maps the container’s port 80 to port 8080 on your host machine. ServBay will then connect to port 8080 on your host.

Based on your application and Dockerfile configuration, make sure that the service inside your container is listening on the correct port, and that you map this port to a host port.

Step 2: Open the ServBay Management Interface

Find the ServBay app in your macOS Applications folder and double-click it to launch the ServBay management interface.

Step 3: Navigate to the Site Management Page

Once ServBay is open, you'll see the main dashboard. In the navigation menu on the left, locate and click the Sites option. This will take you to ServBay’s site management page, where you can view and configure all your locally added websites.

Illustration: Click “Sites” in the left sidebar to access the management page.

Step 4: Add a New Site

At the bottom of the Site Management page, you'll find a + button. Click this, and ServBay will expand a new form on the right, where you can enter details for your new website.

Illustration: Click the “+” button at the bottom of the page to add a new site.

Step 5: Configure Site Settings

In the new site configuration form, fill in the following key details:

1. Name: Enter a recognizable name for your website, such as Docker Nginx Demo. This name is for internal use within ServBay.
2. Domain: Enter the local domain you want to use for accessing this Docker-powered site in your browser. It’s recommended to use the .servbay.demo suffix to avoid conflicts with public domains, e.g., docker.servbay.demo. ServBay will automatically configure your system’s hosts file to point this domain to 127.0.0.1.
3. Protocol: Choose the supported protocol. The default HTTP/HTTPS is usually sufficient. ServBay will listen on both HTTP (80) and HTTPS (443) ports and handle SSL according to your settings.
4. SSL Certificate Request Method: It’s recommended to select ServBay CA. ServBay will automatically generate and manage a locally trusted SSL certificate, signed by the ServBay User CA. By installing the ServBay Public CA into your macOS Keychain, your browser will trust these local certificates, allowing you to develop and test HTTPS locally without hassle. If needed, you can also choose ACME (for Let's Encrypt) or Custom (to use your own certificate).
5. Website Type: [Important] Select Reverse Proxy. This indicates that ServBay will act as the gateway for this domain, forwarding requests to the backend service you specify.
6. IP Address: Input the IP address where your Docker service is listening on the host. For most local Docker setups, this is the loopback address 127.0.0.1.
7. Port: Enter the port number that your Docker service exposes on the host. This should match the <host port> you set in docker run -p <host port>:<container port>. For example, if you used -p 8080:80, enter 8080 here.

Illustration: Fill out the configuration details for the Docker reverse proxy site.

Step 6: Complete and Save the Configuration

Once all required details are filled in, click the Add button at the bottom of the form.

ServBay will process your request, automatically adding the appropriate reverse proxy rules to its web server (such as Caddy or Nginx), and updating your system's hosts file to point your chosen domain to localhost.

After a short moment for ServBay to apply the changes, you’ll be ready to access your newly added domain.

Step 7: Access Your Site and Use Quick Actions

Once the configuration is saved, return to the site management page, where you’ll see your newly added website listed. Make sure its status is displayed as "Running."

Now you can access your custom domain in your browser (for example, http://docker.servbay.demo or https://docker.servbay.demo). If everything is configured correctly, ServBay will forward your requests to your Docker container’s service and display your container’s web content in the browser.

On each site entry in the list, ServBay provides a set of convenient quick action buttons, including:

1. Open Site Root in IDE: (For reverse proxy sites, this button may be inactive or point to ServBay’s configuration directory. Actual behavior depends on your ServBay version and settings.)
2. Open Site in Browser: Instantly open this site’s URL in a new browser tab.
3. View Site Logs: Check access and error logs recorded by ServBay for this site—great for debugging.
4. Pause/Enable Site: Temporarily disable or re-enable ServBay’s reverse proxy for this site.
5. Delete Site: Remove this site's configuration from ServBay.

Illustration: Quick action buttons available for ServBay site list entries.

Notes and Best Practices

• Docker Container Status: Ensure your target Docker container stays running; otherwise, ServBay cannot forward requests successfully.
• Port Mapping: Double-check that your Docker port mapping (the -p flag) matches the port you entered in ServBay, and that the port is not occupied by another application on your host.
• Firewall: Verify your macOS firewall settings to ensure ServBay's ports (usually 80 and 443) and your Docker-exposed host port are not being blocked.
• Docker Network Mode: In most cases, using the default bridge mode with port mapping via the -p flag is the simplest method. If you use host mode, ServBay connects directly to the container’s internal port (e.g., if the container listens on 80, set ServBay’s port to 80). Note, however, that host mode can introduce port conflicts.
• ServBay CA: For hassle-free HTTPS development, it’s highly recommended to install the ServBay Public CA. This allows ServBay’s local certificates to be trusted by your browser, eliminating security warnings.

FAQ & Troubleshooting

Q: After adding a site, I can’t access it—my browser shows a connection error or timeout?

A: Troubleshoot with the following steps:

1. Check ServBay Site Status: On the ServBay management page, ensure the site shows as “Running.”
2. Check Docker Container Status: Run docker ps in your terminal to see if the target container is active.
3. Check Docker Port Mapping: Run docker ps and look at the PORTS column to confirm the host port (e.g., in 0.0.0.0:8080->80/tcp or 127.0.0.1:8080->80/tcp, the 8080) matches what you set in ServBay.
4. Check Internal Service: Ensure the web service inside your Docker container (Nginx, Apache, Node app, etc.) is running on the correct port and without internal errors. View logs with docker logs <container_id_or_name>.
5. Check ServBay Logs: Click the log icon for that site in ServBay to review access and error logs—these may show details on proxy failures.
6. Check System hosts File: While ServBay should handle this automatically, you can manually check /etc/hosts and confirm your domain points to 127.0.0.1.
7. Check Firewall: Ensure neither ServBay’s ports nor your container’s exposed port are blocked by the firewall.

Q: Can ServBay manage the Docker containers themselves?

A: ServBay’s main role is to manage local web services, databases, programming environments, and to route traffic to backend services (including Docker containers). ServBay does not provide full Docker container lifecycle management (such as starting, stopping, or building images). For container management, please use the Docker CLI or Docker Desktop.

Q: What is the ServBay CA and why should I install it?

A: The ServBay CA (Certificate Authority) is ServBay’s certificate management system for easy local HTTPS development. The ServBay User CA signs SSL certificates for your local sites, while the ServBay Public CA is the root certificate. By installing the ServBay Public CA into your macOS Keychain, your operating system and browsers will trust all certificates signed by the ServBay User CA, preventing “insecure connection” warnings when accessing local HTTPS sites. This is crucial for simulating production-like HTTPS environments for local development and testing.

Summary

Adding a website powered by a Docker container in ServBay is an efficient and flexible method, leveraging ServBay as the central hub for local development—handling traffic and domain management—while utilizing Docker for the robust running and isolation of application environments. With a simple reverse proxy configuration, you can quickly integrate any Docker-based project into your ServBay workflow. By following the steps and best practices in this guide, you can easily set up and operate your Dockerized local websites.