Web Service Troubleshooting Guide

ServBay supports using Caddy, NGINX, and Apache as the default web server. In daily use, users may encounter issues such as websites not opening. Below are some common solutions to these problems.

Troubleshooting with Built-in Tools from ServBay

ServBay comes equipped with powerful diagnostic tools. We recommend using the built-in troubleshooting tool for self-diagnosis and resolution.

Open the ServBay application and find Diagnostics in the left navigation menu to access the built-in diagnostics tool.

Check Configuration Files

Checking the Caddyfile

Use Caddy's built-in verification feature to validate if the Caddyfile is correct. Please run the following command:

$ /Applications/ServBay/bin/caddy validate -c /Applications/ServBay/etc/caddy/Caddyfile

If it returns Valid configuration, everything is normal. If it returns another error code, please follow the prompts based on the error code. (Note: The above command will produce a lot of INFO and WARN outputs; this is normal and will not affect the service's operation.)

Certificate Errors

If you encounter an error message like loading certificates: open xxxxx: no such file or directory, it means the certificate file is missing. Please check if the path to the certificate file is correct.

2024/12/09 17:24:16.970 INFO using config from file {"file": "/Applications/ServBay/etc/caddy/Caddyfile"}
2024/12/09 17:24:16.991 INFO adapted config to JSON {"adapter": "caddyfile"}
2024/12/09 17:24:16.991 WARN Caddyfile input is not formatted; run 'caddy fmt --overwrite' to fix inconsistencies {"adapter": "caddyfile", "file": "/Applications/ServBay/etc/caddy/Caddyfile", "line": 8}
2024/12/09 17:24:16.999 INFO tls.cache.maintenance started background certificate maintenance {"cache": "0x1400121f300"}
2024/12/09 17:24:17.006 INFO tls.cache.maintenance stopped background certificate maintenance {"cache": "0x1400121f300"}

Error: loading http app module: provision http: getting tls app: loading tls app module: provision tls: loading certificates: open /Applications/ServBay/ssl/private/tls-certs/mail.servbay.host/mail.servbay.host.1crt: no such file or directory

Website Directory Errors

If you see the error message parsing caddyfile tokens for 'root': too many arguments, please check if there are spaces in the directory path. This is a very common error.

For example, root * /Applications/ServBay/www/public web has a space between public and web, which is treated as two arguments, causing an error. The correct way to set this is to wrap the path in double quotes ("). For example, root * "/Applications/ServBay/www/public web".

We strongly recommend not including spaces or special characters in any filenames or paths. You can use - or _ symbols to separate words, such as: public-folder, public_dir.

2024/12/09 17:26:37.371 INFO using config from file {"file": "/Applications/ServBay/etc/caddy/Caddyfile"}

Error: adapting config using caddyfile: parsing caddyfile tokens for 'root': too many arguments; should only be a matcher and a path, at /Applications/ServBay/etc/caddy/Caddyfile:1388

Rewrite Rule Errors

Using incorrect Rewrite rules in Caddy, such as directly applying NGINX rules, can also lead to errors.

NGINX Configuration Check

Use the following command to check if the NGINX configuration is correct:

$ /Applications/ServBay/bin/nginx -t

If the configuration is correct, you will see:

nginx: the configuration file /Applications/ServBay/etc/nginx/nginx.conf syntax is ok
nginx: configuration file /Applications/ServBay/etc/nginx/nginx.conf test is successful

Common errors include:

1. Syntax errors (e.g., missing semicolons)
2. Incorrect file paths
3. Port conflicts

Apache Configuration Check

Use the following command to check Apache configuration:

$ /Applications/ServBay/bin/apachectl configtest

Common errors include:

1. Module loading failures
2. Syntax errors in .htaccess files
3. Incorrect directory permissions

Handling 500 Errors

A 500 Internal Server Error is a common Web server error that can be caused by various reasons:

General Troubleshooting Steps

1. Check server error logs:

   • Caddy: /Applications/ServBay/var/logs/caddy/error.log
   • NGINX: /Applications/ServBay/var/logs/nginx/error.log
   • Apache: /Applications/ServBay/var/logs/apache/error.log

2. Check if the PHP service is running:

   ps aux | grep php-fpm

3. Check PHP errors (if using PHP):

   • /Applications/ServBay/var/logs/php/php_error.log

4. Check file permissions:

   $ ls -la /Applications/ServBay/www/your-site

   Ensure the web server user has read permissions.

Caddy-Specific 500 Errors

1. Check if FastCGI configurations are correct.
2. Ensure PHP-FPM service is running.
3. Validate reverse proxy settings.

NGINX-Specific 500 Errors

1. Check if fastcgi_pass settings are correct.
2. Validate if client_max_body_size is large enough.
3. Check the configuration of the try_files directive.

Apache-Specific 500 Errors

1. Check if mod_rewrite is enabled.
2. Validate the content of the .htaccess file.
3. Check the AllowOverride settings.

Service Management

Restarting Services

If configurations are modified, you need to restart the corresponding services:

# Caddy
$ servbayctl restart caddy -all

# NGINX
$ servbayctl restart nginx -all

# Apache
$ servbayctl restart apache -all

Viewing Service Status

# Caddy
$ servbayctl status caddy -all

# NGINX
$ servbayctl status nginx -all

# Apache
$ servbayctl status apache -all

Advanced Troubleshooting

If the above methods do not resolve the issue, you may try:

1. Temporarily disabling the firewall for testing.
2. Using curl -v to view detailed request information.
3. Testing on different browsers/devices.
4. Checking if DNS resolution is correct.

For further assistance, please contact the ServBay technical support team.