NGINX to Caddy & Caddyfile Converter

What does the NGINX to Caddy & Caddyfile Converter do?

The NGINX to Caddy Converter translates NGINX server {} blocks and sites-available configuration files into clean Caddy v2 Caddyfile syntax. It converts reverse proxy targets (proxy_pass), URI location blocks, static root directories, single-page app (SPA) fallback rules (try_files), FastCGI PHP-FPM sockets, redirects, and custom header definitions into concise Caddy directives while removing redundant TLS certificates and proxy headers managed automatically by Caddy.

Core Concepts

Understanding key configuration differences between NGINX and Caddy helps during migration:

• Automatic HTTPS by Default: Caddy automatically provisions and renews TLS certificates via Let's Encrypt / ZeroSSL for any domain name without requiring manual ssl_certificate or ssl_certificate_key directives.
• Built-in Reverse Proxy Headers: Unlike NGINX, which requires explicit proxy_set_header Host $host and proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for configuration lines, Caddy's reverse_proxy passes standard forwarding headers to upstreams automatically.
• Location Matching and Syntax: NGINX location prefixes (e.g. location /api/ { proxy_pass ...; }) map directly to path-scoped Caddy directives (e.g. reverse_proxy /api/* 127.0.0.1:8080).

How to use the tool?

1. Paste NGINX Configuration: Paste your full NGINX server {} block, nginx.conf snippet, or sites-available file into the editor.
2. Review Converted Caddyfile: The editor converts proxy passes, static roots, try_files SPA fallbacks, and PHP-FPM sockets into clean Caddy v2 syntax.
3. Copy or Download: Click Copy or Download to save your Caddyfile.
4. Validate & Reload: Run caddy validate --config Caddyfile locally in your terminal and reload the daemon with caddy reload.

Related Developer Utilities

If you are configuring web servers, proxies, or Linux services, explore these complementary tools:

• NGINX Location Matcher: Test and debug NGINX URI prefix, regex, and exact match precedence rules.
• Crontab to Systemd Timer Generator: Convert traditional cron schedules into Systemd timers and service units.
• Linux Logrotate Generator: Generate log rotation configurations with copytruncate for NGINX and Caddy access logs.

REST API Integration

Blueutils provides a free REST API endpoint (POST https://blueutils.com/api/nginx/nginx-to-caddy) to programmatically convert NGINX server {} blocks, reverse proxy directives, fastcgi PHP handlers, and rewrites into modern Caddy v2 Caddyfile syntax.

API Request Parameters

API Request Payload Examples

cURL

curl -X POST https://blueutils.com/api/nginx/nginx-to-caddy \
  -H "Content-Type: application/json" \
  -d '{
    "rawText": "server {\n  listen 80;\n  server_name example.com;\n  location /api/ {\n    proxy_pass http://127.0.0.1:8080;\n  }\n}"
  }'

Python

import requests

url = "https://blueutils.com/api/nginx/nginx-to-caddy"
payload = {
    "rawText": "server {\n  listen 80;\n  server_name example.com;\n  location /api/ {\n    proxy_pass http://127.0.0.1:8080;\n  }\n}"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        String jsonPayload = """
            {
                "rawText": "server {\\n  listen 80;\\n  server_name example.com;\\n  location /api/ {\\n    proxy_pass http://127.0.0.1:8080;\\n  }\\n}"
            }
            """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://blueutils.com/api/nginx/nginx-to-caddy"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

API Response Parameters

API Response Payload Examples

Success Response (HTTP 200 OK)

{
  "isValid": true,
  "serverCount": 1,
  "converted": "example.com {\n\treverse_proxy /api/* 127.0.0.1:8080\n}"
}

Validation Failure Response (HTTP 400 Bad Request)

{
  "isValid": false,
  "error": "NGINX configuration cannot be empty."
}

Rate Limit Exceeded Response (HTTP 429 Too Many Requests)

{
  "error": "API rate limit exceeded. Please wait or contact support@blueutils.com."
}

Why use an API to convert NGINX to Caddy?

Integrating the NGINX to Caddy converter API into migration scripts, container initialization jobs, or CI/CD pipelines provides several advantages:

• Rapid Script Validation: Enables developers and infrastructure teams to convert and verify hundreds of legacy NGINX virtual hosts into Caddyfile blocks automatically during server migration.
• Optimized Token Efficiency for AI Agents: Offloading configuration parsing, regex location mapping, and header stripping to an API saves substantial context tokens during autonomous migration workflows.
• Deterministic Accuracy Without Hallucinations: Guarantees deterministic translation of complex upstream proxy passes, FastCGI PHP sockets, and SPA fallback rewrites without LLM syntax hallucinations.

Native Usage

How to validate and test Caddyfile configurations locally:

Windows (CMD / PowerShell)

# Validate Caddyfile syntax without starting the server
caddy.exe validate --config .\Caddyfile

# Hot reload active Caddy service with zero downtime
caddy.exe reload --config .\Caddyfile

Linux / Unix (Bash)

# Validate Caddyfile syntax
caddy validate --config /etc/caddy/Caddyfile

# Apply changes with zero-downtime hot reload
caddy reload --config /etc/caddy/Caddyfile

Python

Using Python standard library to run caddy validate on converted files:

import subprocess

def validate_caddyfile(caddyfile_path="Caddyfile"):
    result = subprocess.run(["caddy", "validate", "--config", caddyfile_path], capture_output=True, text=True)
    if result.returncode == 0:
        print("Caddyfile syntax is valid!")
    else:
        print("Validation errors:", result.stderr)

validate_caddyfile("Caddyfile")

Java

Using Java ProcessBuilder to validate Caddy configuration files:

import java.io.BufferedReader;
import java.io.InputStreamReader;

public class CaddyValidator {
    public static void main(String[] args) {
        ProcessBuilder pb = new ProcessBuilder("caddy", "validate", "--config", "/etc/caddy/Caddyfile");
        pb.redirectErrorStream(true);

        try {
            Process process = pb.start();
            try (BufferedReader reader = new BufferedReader(new InputStreamReader(process.getInputStream()))) {
                String line;
                while ((line = reader.readLine()) != null) {
                    System.out.println(line);
                }
            }
            int exitCode = process.waitFor();
            System.out.println("Caddy validation exit code: " + exitCode);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}