Adding a Website with Custom Configuration

ServBay offers flexible ways to add websites. In addition to the standard mode, where configurations are managed automatically by ServBay, there’s also a “Custom Configuration” mode. This mode enables developers to write and manage website-specific web server configuration files directly (Nginx, Caddy, or Apache), delivering maximum flexibility and control—ideal for highly tailored requirements, non-standard setups, or advanced features.

The Value of Custom Configuration

Choosing custom configuration means:

1. Full control: You can directly edit the server configuration fragment for your site (such as the Nginx server block, Apache VirtualHost block, or Caddy site definition).
2. Advanced features: Easily achieve tasks that are difficult or impossible with the standard mode, such as complex rewrite rules, specific proxy settings, custom log formats, or specialized security headers.
3. Special scenarios: Perfect for simulating production environments, integrating special modules, or deep debugging requirements.

However, this also means you are solely responsible for the correctness and security of your configuration, including SSL certificate management.

Steps to Add a Custom Configuration Website

1. Go to Websites: In ServBay’s left menu, click Websites.
2. Add a New Website: Click the + (plus) button above the site list.
3. Fill in Basic Information:
   • Name: Give your website an easily identifiable name (e.g., My Custom Project).
   • Domain: Enter the domain you want to use for local access (e.g., myproject.servbay.demo).
4. Choose Web Server: Select your preferred web server from the Web Server dropdown (Nginx, Caddy, or Apache). This selection is crucial as it determines the configuration template and which server software will serve the site.
5. Enable Custom Configuration: Check the Custom Configuration checkbox.
6. View and Edit Template: Once checked, a text area below will auto-populate with a basic configuration template for your chosen web server. This is your starting point—you will (and typically should) edit it as needed.

Understanding and Modifying the Configuration Template

ServBay offers different configuration templates based on your chosen web server (Nginx, Caddy, or Apache). You should tailor these templates to your project’s actual needs.

1. Nginx Custom Configuration

If you select Nginx, ServBay provides a basic server block template.

Template Structure & Key Directives:

# Listen ports and protocol
listen 443 ssl; # HTTPS

# Bound domain name
server_name myproject.servbay.demo;

# Website root directory (ensure this directory exists)
root /Applications/ServBay/www/myproject.servbay.demo;

# Default index files
index index.php index.html index.htm;

# SSL/TLS protocols and ciphers (example)
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers 'TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384';
ssl_prefer_server_ciphers on;
ssl_session_timeout 1d;
ssl_session_cache shared:ServBay:10m;
ssl_session_tickets off;

# SSL certificate paths (must be specified manually if HTTPS is enabled)
# [IMPORTANT] Ensure certificate files exist and paths are correct
ssl_certificate /Applications/ServBay/ssl/private/tls-certs/myproject.servbay.demo/myproject.servbay.demo.crt;
ssl_certificate_key /Applications/ServBay/ssl/private/tls-certs/myproject.servbay.demo/myproject.servbay.demo.key;

# Handle PHP requests (example for PHP 8.3—adjust as needed)
set $php_version '8.3';
include enable-php-fpm-pathinfo.conf;

# Other configurations, like location blocks, rewrite rules, etc.
location / {
    try_files $uri $uri/ /index.php?$query_string;
}

# Access and error log paths (optional)
# access_log /Applications/ServBay/logs/nginx/myproject.servbay.demo-access.log;
# error_log /Applications/ServBay/logs/nginx/myproject.servbay.demo-error.log;

Modification Points:

• Verify that server_name matches your designated domain.
• Set the correct root directory for your project files.
• If HTTPS is required, uncomment or add listen 443 ssl; and be sure to provide correct paths to ssl_certificate and ssl_certificate_key.
• Add additional location blocks, rewrite rules, proxy configurations, etc., as needed.

2. Caddy Custom Configuration

If you select Caddy, ServBay provides a template formatted as a Caddyfile site definition.

Template Structure & Key Directives:

encode zstd gzip
import set-log myproject.servbay.demo   # log filename

import canonical-path

# Website root directory (ensure this directory exists)
root * /Applications/ServBay/www/myproject.servbay.demo

# Handle PHP requests
route {
    import php-rewrite-default 8.3  # PHP version 8.3
}

# TLS/SSL settings
# Please specify certificate paths
# tls /Applications/ServBay/ssl/private/tls-certs/myproject.servbay.demo/myproject.servbay.demo.crt /Applications/ServBay/ssl/private/tls-certs/myproject.servbay.demo/myproject.servbay.demo.key

# Enable file server
file_server

# Other directives, such as reverse_proxy, rewrite, header, etc.
# ...

Modification Points:

• Ensure the top-level domain myproject.servbay.demo is correct.
• Set the root directive to your project’s actual directory.
• SSL/TLS: By default, Caddy attempts automatic HTTPS certificate management. This won’t work for local domains like .servbay.demo. If you need HTTPS, it is strongly recommended to use the tls directive to manually specify your own certificate and key file paths. Make sure the files exist and paths are correct.
• Add other Caddy directives as required.

3. Apache Custom Configuration

If you select Apache, ServBay provides a <VirtualHost> block template.

Template Structure & Key Directives:

ServerName myproject.servbay.demo
DocumentRoot "/Applications/ServBay/www/myproject.servbay.demo"

# Enable SSL engine
SSLEngine on

# SSL certificate paths
# [IMPORTANT] Ensure certificate files exist and paths are correct
SSLCertificateFile "/Applications/ServBay/ssl/private/tls-certs/myproject.servbay.demo/myproject.servbay.demo.crt"
SSLCertificateKeyFile "/Applications/ServBay/ssl/private/tls-certs/myproject.servbay.demo/myproject.servbay.demo.key"

# Directory permissions
<Directory "/Applications/ServBay/www/myproject.servbay.demo">
    DirectoryIndex index.php index.html index.htm
    Options FollowSymLinks
    AllowOverride All
    Require all granted
</Directory>

# PHP-FPM configuration (PHP 8.3)
Define PHP_VERSION 8.3
<FilesMatch \.php$>
    SetHandler "proxy:unix:/Applications/ServBay/tmp/php-cgi-${PHP_VERSION}.sock|fcgi://localhost"
</FilesMatch>

# Error and access logs (optional)
ErrorLog "/Applications/ServBay/logs/apache/myproject.servbay.demo-ssl-error_log"
CustomLog "/Applications/ServBay/logs/apache/myproject.servbay.demo-ssl-access_log" common

Modification Points:

• Verify that ServerName matches your chosen domain.
• Set the correct DocumentRoot to your project’s directory.
• Configure the permissions and options of the <Directory> block.
• Add other Apache directives as needed, such as RewriteEngine, ProxyPass, etc.

SSL Certificate Management [IMPORTANT]

When using custom configuration, ServBay will not automatically generate SSL certificates for you (for example, creating a ServBay CA certificate or using the ACME protocol to apply for a Let’s Encrypt certificate).

• You are fully responsible for obtaining or generating SSL certificates and placing them in a location accessible by your server.
• You may use OpenSSL to manually generate self-signed certificates or use ServBay's CA (ServBay User CA or ServBay Public CA) to issue local development certificates.
• In your Nginx, Caddy, or Apache custom configuration, you must properly specify ssl_certificate / ssl_certificate_key (Nginx), tls (Caddy), or SSLCertificateFile / SSLCertificateKeyFile (Apache) directives, pointing to your prepared certificate and key files.
• If your configuration contains SSL-related directives but the certificate files are missing or paths are incorrect, the web server will fail to start or apply the site’s configuration. The website will be inaccessible, and you may see errors in the ServBay dashboard or server logs.

For details on generating and managing local development certificates, refer to the ServBay SSL certificate management documentation.

Web Server Binding

DANGER

A crucial point is that once you choose a specific web server (e.g., Nginx) and save the site with a custom configuration, that site's configuration becomes bound to Nginx.

• This means the website can only be accessed when the ServBay's active web server package is set to Nginx.
• If you switch the Service > Default Web Server in ServBay to Apache or Caddy, any website using a custom Nginx configuration will become inaccessible, since its Nginx configuration won’t be loaded.
• The same applies vice versa: sites configured for Caddy or Apache in custom mode can only be accessed when their respective server package is active.

Saving and Applying Changes

After all configuration changes, click the Save button at the bottom right. ServBay will save your custom configuration and attempt to reload the relevant web server for your changes to take effect. If there are syntax errors, saving or reloading may fail. Check ServBay notifications or the error logs of the appropriate server (typically under /Applications/ServBay/logs/ in the corresponding subdirectory) to troubleshoot issues.

Summary

Adding websites using custom configuration empowers ServBay users with unmatched flexibility, giving developers precise, hands-on control over server behavior for each site. However, it requires familiarity with web server configuration and a willingness to take responsibility for correct settings, security, and SSL management. Mastering the template structure, SSL requirements, and the server binding mechanism is key to successful use of this feature.