Rewrite and .htaccess: Key Differences and Considerations When Migrating from NGINX and Apache to Caddy in ServBay

Background Information

URL Rewrite (commonly referred to as Rewrite or URL rewriting), also known as pseudo-static, is a technique for dynamically modifying request URLs at the web server level. It allows the original URLs accessed by users or search engines (e.g., /?page=123) to be internally rewritten by the server to a different URL (e.g., /posts/123/), while the user still sees the rewritten URL in the browser’s address bar. This technology is widely applied to:

• Beautify URL Structure: Creating cleaner, more readable, memorable, and shareable URLs.
• Enhance SEO: Search engines prefer descriptive and well-structured URLs.
• Hide Internal Implementation Details: Prevent exposing file paths or query parameters to improve security.
• URL Normalization: Enforce specific URL formats (e.g., with or without www, using HTTPS).
• Enable Routing: Modern web frameworks frequently use Rewrite rules to route all requests to a single entry file (such as index.php), allowing the framework to handle all incoming requests.

Understanding and configuring Rewrite rules is an essential skill in web development.

ServBay's Support for NGINX and Apache

ServBay comes with full built-in support for both NGINX and Apache web servers. Users can easily switch the default web server according to project requirements or personal preferences.

To learn how to switch the default web server, see the documentation: How to Set the Default Web Server

ServBay provides developers with popular web server options including Caddy, NGINX, and Apache. To simplify local development configurations, ServBay comes pre-configured with common Rewrite rules for both Caddy and NGINX, covering the needs of most modern web frameworks and CMSs. This means that for many common applications—such as PHP-based WordPress, Laravel, Symfony, and others—no further Rewrite configuration is usually required in the ServBay environment; applications can run out of the box.

However, for developers accustomed to Apache or NGINX who are planning to, or are already in the process of migrating their existing site or project to the Caddy server built into ServBay, it’s crucial to understand the differences in Rewrite rule configuration. This article details the differences in Rewrite configurations among Apache, NGINX, and Caddy, and provides important considerations for migration.

Out-of-the-Box Rewrite Rules: The ServBay Advantage

Important Note

One of ServBay’s core design philosophies is to simplify the setup and configuration of the local development environment. For most mainstream web applications and frameworks, ServBay already comes with robust, pre-configured Rewrite rules. This means that when running these applications in ServBay, you usually don’t need to manually write or modify Rewrite rules—ServBay has already handled these essential configurations for you.

If you’re migrating a site that originally ran on Apache or NGINX to the Caddy environment in ServBay and need to handle complex custom Rewrite rules, please refer to the detailed migration guides below:

• Migrating an NGINX Site to ServBay (Caddy)
• Migrating an Apache Site to ServBay (Caddy)

Introduction to Rewrite Rules in Web Servers

Different web servers employ different syntaxes and configuration file structures for defining Rewrite rules. Understanding these differences is essential for successful cross-server migration. This section offers a concise overview of how Apache, NGINX, and Caddy each approach Rewrite configuration.

Apache’s .htaccess File

The Apache HTTP Server uses .htaccess files to configure Rewrite rules. .htaccess files are distributed configuration files typically placed in the website root or specific subdirectories. They allow directory-level overrides of the main server configurations and apply to their containing directory as well as all subdirectories (unless a subdirectory has its own .htaccess). Apache handles URL rewriting through the mod_rewrite module.

Basic Usage Example

Below is a common .htaccess example, often used to rewrite all requests for nonexistent files or directories to index.php—a standard approach for PHP frameworks and CMSs:

# Enable Rewrite Engine
RewriteEngine On

# If the requested file or directory does not exist, process the Rewrite rule
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d

# Rewrite all requests to index.php, keeping query strings intact
RewriteRule ^(.*)$ index.php [L,QSA]

Explanation:

• RewriteEngine On: Enables rewriting in the current directory.
• RewriteCond %{REQUEST_FILENAME} !-f: Checks if the requested file path (%{REQUEST_FILENAME}) is not an existing file (!-f).
• RewriteCond %{REQUEST_FILENAME} !-d: Checks if the requested path is not an existing directory (!-d).
• RewriteRule ^(.*)$ index.php [L,QSA]: The rewriting rule itself.
  • ^(.*)$: Matches any URL path.
  • index.php: Rewrites the matched path to index.php.
  • [L]: 'Last' flag—this rule is the last to be applied for the current request.
  • [QSA]: 'Query String Append'—appends the original query string to the rewritten URL.

NGINX Rewrite Rules

NGINX uses its main configuration file (nginx.conf) or site-specific files (commonly under conf.d or sites-available/sites-enabled) to define Rewrite rules. Rules in NGINX are generally set inside a server block (defining a virtual host) or a location block (targeting specific URL paths). The NGINX Rewrite module (ngx_http_rewrite_module) is quite powerful, but notably uses a different syntax than Apache.

Basic Usage Example

Here’s a basic NGINX configuration snippet to achieve similar logic—rewriting requests to index.php:

server {
    listen 80;
    server_name servbay.demo; # Example ServBay domain

    root /Applications/ServBay/www/demo; # Example site root

    # Try files/directories in order, then rewrite to index.php
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    # Handle .php requests by forwarding them to PHP-FPM/FastCGI
    location ~ \.php$ {
        # Ensure the file exists, preventing arbitrary execution
        try_files $uri =404;
        include fastcgi_params;
        # Default PHP FastCGI socket path in ServBay
        fastcgi_pass unix:/Applications/ServBay/tmp/php-cgi.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
}

Explanation:

• location /: Matches requests at the site root.
• try_files $uri $uri/ /index.php?$query_string;: A commonly used directive that:
  1. Tries to find a file matching the requested URI ($uri).
  2. Tries to find a directory matching the requested URI ($uri/).
  3. If neither exists, internally rewrites to /index.php, preserving the original query string (?$query_string).
• location ~ \.php$: Uses a regex to match all requests ending in .php.
• fastcgi_pass unix:/Applications/ServBay/tmp/php-cgi.sock;: Forwards PHP requests to ServBay’s default PHP FastCGI handler.

Caddy Rewrite Rules

Caddy uses its own Caddyfile configuration format. The Caddyfile is designed to be simple, easy to read, and powerful. Its syntax is quite different from Apache or NGINX, but generally more intuitive. Caddy’s Rewrite capabilities are provided using the rewrite directive, paired with flexible matchers.

Basic Usage Example

Below is a typical Caddyfile snippet showing how to rewrite requests to index.php:

servbay.demo { # Example ServBay domain
    root * /Applications/ServBay/www/demo # Example site root

    # Forward PHP requests to ServBay’s default PHP FastCGI handler
    php_fastcgi unix//Applications/ServBay/tmp/php-cgi.sock

    # Serve static files
    file_server

    # Define a matcher @notStatic: if the requested file or directory does not exist
    @notStatic {
        not {
            file {
                # Try to find file {path} or directory {path}/
                # If neither exists, this matcher (@notStatic) triggers
                try_files {path} {path}/
            }
        }
    }

    # If @notStatic is triggered, rewrite the request to /index.php
    rewrite @notStatic /index.php
}

Explanation:

• servbay.demo { ... }: Defines a site block for the servbay.demo domain.
• root * /Applications/ServBay/www/demo: Sets the site root for all requests.
• php_fastcgi unix//Applications/ServBay/tmp/php-cgi.sock: A built-in Caddy directive that automatically forwards .php (and other relevant) requests to the PHP FastCGI handler—ServBay has already set up this path.
• file_server: Serves static files, attempting to directly serve any requested file or directory.
• @notStatic { ... }: Names a matcher called notStatic.
• not { file { try_files {path} {path}/ } }: The matcher’s logic—is true if neither the requested file {path} nor directory {path}/ exists.
• rewrite @notStatic /index.php: If notStatic matcher is true, internally rewrites the request to /index.php.

In ServBay’s default setup, the php_fastcgi directive already includes similar try_files logic, and ServBay automatically generates a base Caddyfile for new sites, providing out-of-the-box compatibility for most frameworks. The example above demonstrates how you could implement this logic natively in Caddy.

Points to Note When Migrating from Apache or NGINX to Caddy in ServBay

When migrating a site from Apache or NGINX to Caddy in ServBay, translating Rewrite rules is a critical step. Although ServBay comes preconfigured with most commonly used rules, if your project uses custom rules, you’ll need to understand and handle the conversion manually.

Be sure to reference the dedicated migration guides:

• Migrating an Apache Site to ServBay (Caddy)
• Migrating an NGINX Site to ServBay (Caddy)

Key differences to pay attention to during migration:

1. Syntax and Configuration Location for Rewrite Rules:

   • Apache: Uses .htaccess files (distributed, per-directory) or main configs (httpd.conf/site configs). Rules largely rely on the RewriteRule and RewriteCond directives, with syntax primarily based on regular expressions.
   • NGINX: Uses centralized configs (nginx.conf) and site config files. Rules typically employ location blocks, the rewrite, if, and try_files directives, and a syntax distinct from Apache.
   • Caddy: Uses the centralized Caddyfile. Rules use the rewrite directive together with flexible matchers (file, path, header, etc.) to build complex matching logic, with syntax that is both straightforward and readable.
   • Conversion: Porting Apache .htaccess or NGINX location/rewrite/try_files rules to Caddyfile syntax involves translation between different paradigms. There’s no simple one-to-one automatic converter that handles all scenarios perfectly; manual conversion is usually required. It’s best to consult Caddy’s official documentation on rewrites and matchers to understand the principles.

2. Config File Structure:

   • Apache: Allows per-directory .htaccess alongside centralized configuration via the main config file (typically with one VirtualHost per site).
   • NGINX: Centralizes configuration in nginx.conf and included site config files, organized using server and location blocks.
   • Caddy: Uses a flat, intuitive structure in the Caddyfile—sites are defined by address (e.g., servbay.demo), with directives inside each site block. Caddyfile structures are typically less nested and more readable than NGINX configs.

3. Module and Directive Mapping:

   • Apache and NGINX both provide extensive modules and directives. Caddy also includes a rich set of built-in capabilities, but names and methods differ. For example, Apache’s mod_rewrite functionality is implemented with Caddy’s rewrite directive and matchers; NGINX's try_files has an equivalent in Caddy, used inside the file matcher or built into directives like php_fastcgi.
   • During migration, refer to Caddy’s documentation to identify and understand the necessary directives.

4. Default Behaviors and Rule Priorities:

   • Each server handles requests and applies rules in its own way. For example: how Apache processes .htaccess files, the precedence of NGINX location blocks, or the order of execution in the Caddyfile (which prioritizes sequential order in most cases).
   • After migration, thoroughly test all URL paths to ensure Rewrite rules function as intended. Pay special attention to the fact that ServBay’s Caddy default configuration may already include the basic rules you require—avoid duplicating or conflicting configurations.

Summary

ServBay provides local development environments with Caddy, NGINX, and Apache web servers. Although ServBay comes with preconfigured Rewrite rules for Caddy and NGINX covering most common use cases—making major frameworks ready to use out of the box—developers migrating from custom Apache or NGINX setups to Caddy must understand the differences in Rewrite rule configuration.

Apache relies on distributed configuration with .htaccess and RewriteRule/RewriteCond; NGINX uses centralized config files with location/rewrite/try_files directives; Caddy employs the clean, readable Caddyfile and rewrite directive in combination with powerful matchers.

The crux of migration is accurately translating the existing Apache or NGINX rewrite logic into Caddyfile syntax. While this requires some learning and manual work, Caddy’s straightforward configuration—combined with ServBay’s presets and detailed migration guides—makes the process much easier. We hope this article helps you understand these differences and enables efficient web development in the ServBay environment.