vhosts.json

{
  "description": "FastHTTP Virtual Host Configuration Examples",
  "examples": [
    {
      "name": "Basic Static Website",
      "description": "Simple static website serving HTML, CSS, and JavaScript files",
      "config": {
        "serverName": "example.com",
        "documentRoot": "/var/www/example.com/public_html",
        "user": "www-data",
        "group": "www-data",
        "directoryIndex": "index.html index.htm"
      }
    },
    {
      "name": "PHP Website with FastCGI (TCP)",
      "description": "PHP website using FastCGI over TCP connection",
      "config": {
        "serverName": "phpapp.com",
        "documentRoot": "/var/www/phpapp.com/public_html",
        "user": "phpapp",
        "group": "phpapp",
        "phpProxyFCGI": "127.0.0.1:9000",
        "directoryIndex": "index.php index.html"
      }
    },
    {
      "name": "PHP Website with FastCGI Proxy (Unix Socket)",
      "description": "PHP website using FastCGI over Unix socket proxy",
      "config": {
        "serverName": "phpapp2.com",
        "documentRoot": "/var/www/phpapp2.com/public_html",
        "user": "phpapp2",
        "group": "phpapp2",
        "proxyUnixSocket": "/run/php-fpm/php-fpm.sock",
        "proxyType": "fcgi",
        "directoryIndex": "index.php index.html index.htm"
      }
    },
    {
      "name": "CGI Scripts Support",
      "description": "Virtual host with CGI script execution support",
      "config": {
        "serverName": "cgi.example.com",
        "documentRoot": "/var/www/cgi.example.com/public_html",
        "user": "cgiuser",
        "group": "cgigroup",
        "cgiPath": "/cgi-bin",
        "directoryIndex": "index.cgi index.html"
      }
    },
    {
      "name": "HTTP Proxy to Backend Service",
      "description": "Proxies requests to a backend HTTP service over Unix socket",
      "config": {
        "serverName": "api.example.com",
        "documentRoot": "/var/www/api.example.com",
        "user": "apiuser",
        "group": "apiuser",
        "proxyUnixSocket": "/var/run/backend-api.sock",
        "proxyType": "http",
        "proxyPath": "/api"
      }
    },
    {
      "name": "FastCGI Proxy with Path Prefix",
      "description": "Proxies specific paths to FastCGI backend, rest serves static files",
      "config": {
        "serverName": "mixed.example.com",
        "documentRoot": "/var/www/mixed.example.com/public_html",
        "user": "mixeduser",
        "group": "mixeduser",
        "proxyUnixSocket": "/run/app-fcgi.sock",
        "proxyType": "fcgi",
        "proxyPath": "/app",
        "directoryIndex": "index.html"
      }
    },
    {
      "name": "Custom Directory Index Order",
      "description": "Virtual host with custom directory index file priority",
      "config": {
        "serverName": "custom.example.com",
        "documentRoot": "/var/www/custom.example.com/public_html",
        "user": "customuser",
        "group": "customuser",
        "directoryIndex": "home.php welcome.html index.php index.html"
      }
    },
    {
      "name": "HTTPS Virtual Host (with SSL)",
      "description": "HTTPS virtual host configuration (SSL configuration would be separate)",
      "config": {
        "serverName": "secure.example.com",
        "serverAlias": ["www.secure.example.com"],
        "documentRoot": "/var/www/secure.example.com/public_html",
        "user": "secureuser",
        "group": "secureuser",
        "directoryIndex": "index.php index.html"
      }
    },
    {
      "name": "Multiple Server Aliases",
      "description": "Virtual host with multiple domain aliases",
      "config": {
        "serverName": "example.com",
        "serverAlias": ["www.example.com", "example.net", "www.example.net"],
        "documentRoot": "/var/www/example.com/public_html",
        "user": "example",
        "group": "example",
        "directoryIndex": "index.html index.htm"
      }
    },
    {
      "name": "Complete Configuration with All Options",
      "description": "Example showing all available configuration options",
      "config": {
        "listen": ["80", "8080"],
        "serverName": "full.example.com",
        "serverAlias": ["www.full.example.com"],
        "documentRoot": "/var/www/full.example.com/public_html",
        "user": "fulluser",
        "group": "fullgroup",
        "serverAdmin": "admin@full.example.com",
        "errorLog": "/var/log/fasthttp/full.example.com-error.log",
        "customLog": "/var/log/fasthttp/full.example.com-access.log",
        "directoryIndex": "index.php index.html index.htm",
        "phpProxyFCGI": "127.0.0.1:9000",
        "cgiPath": "/cgi-bin",
        "proxyUnixSocket": "/var/run/full-app.sock",
        "proxyType": "fcgi",
        "proxyPath": "/api"
      }
    }
  ],
  "locationExamples": [
    {
      "name": "Virtual Host with Location Blocks",
      "description": "Example showing location/directory-based configuration like nginx/httpd",
      "config": {
        "serverName": "example.com",
        "documentRoot": "/var/www/example.com/public_html",
        "user": "example",
        "group": "example",
        "directoryIndex": "index.php index.html",
        "locations": [
          {
            "path": "/api",
            "handler": "proxy",
            "proxyUnixSocket": "/var/run/api-backend.sock",
            "proxyType": "http"
          },
          {
            "path": "/cgi-bin",
            "handler": "cgi",
            "cgiPath": "/cgi-bin"
          },
          {
            "path": "/app",
            "handler": "proxy",
            "proxyUnixSocket": "/run/app-fcgi.sock",
            "proxyType": "fcgi"
          },
          {
            "path": "/static",
            "handler": "static",
            "directoryIndex": "index.html"
          }
        ]
      }
    },
    {
      "name": "Mixed Configuration with Locations",
      "description": "Virtual host with both global and location-specific handlers",
      "config": {
        "serverName": "mixed.example.com",
        "documentRoot": "/var/www/mixed.example.com/public_html",
        "user": "mixeduser",
        "group": "mixeduser",
        "phpProxyFCGI": "127.0.0.1:9000",
        "locations": [
          {
            "path": "/api/v1",
            "handler": "proxy",
            "proxyUnixSocket": "/var/run/api-v1.sock",
            "proxyType": "http"
          },
          {
            "path": "/api/v2",
            "handler": "proxy",
            "proxyUnixSocket": "/var/run/api-v2.sock",
            "proxyType": "http"
          },
          {
            "path": "/legacy",
            "handler": "cgi",
            "cgiPath": "/legacy"
          }
        ]
      }
    },
    {
      "name": "Location \"/\" as Catch-All",
      "description": "Using location \"/\" as default/catch-all handler (like nginx location /)",
      "config": {
        "serverName": "catchall.example.com",
        "documentRoot": "/var/www/catchall.example.com/public_html",
        "user": "catchall",
        "group": "catchall",
        "locations": [
          {
            "path": "/api",
            "handler": "proxy",
            "proxyUnixSocket": "/var/run/api.sock",
            "proxyType": "http"
          },
          {
            "path": "/cgi-bin",
            "handler": "cgi",
            "cgiPath": "/cgi-bin"
          },
          {
            "path": "/",
            "handler": "proxy",
            "proxyUnixSocket": "/run/default-fcgi.sock",
            "proxyType": "fcgi",
            "directoryIndex": "index.php index.html"
          }
        ]
      }
    },
    {
      "name": "Location with Regex Matching",
      "description": "Using regex patterns for location matching (like nginx location ~)",
      "config": {
        "serverName": "regex.example.com",
        "documentRoot": "/var/www/regex.example.com/public_html",
        "user": "regexuser",
        "group": "regexuser",
        "locations": [
          {
            "path": "^/api/v[0-9]+/",
            "matchType": "regex",
            "handler": "proxy",
            "proxyUnixSocket": "/var/run/api-versioned.sock",
            "proxyType": "http"
          },
          {
            "path": "\\.(php|phtml)$",
            "matchType": "regexCaseInsensitive",
            "handler": "proxy",
            "proxyUnixSocket": "/run/php-fpm.sock",
            "proxyType": "fcgi"
          },
          {
            "path": "^/static/.*\\.(css|js|jpg|png|gif)$",
            "matchType": "regex",
            "handler": "static"
          },
          {
            "path": "/cgi-bin",
            "matchType": "prefix",
            "handler": "cgi",
            "cgiPath": "/cgi-bin"
          },
          {
            "path": "/",
            "matchType": "prefix",
            "handler": "static"
          }
        ]
      }
    }
  ],
  "notes": {
    "directoryIndex": "Can be set globally in main config or per virtual host. Virtual host setting overrides global. Default order: index.html, index.htm, index.php",
    "proxyType": "Can be 'http' for HTTP reverse proxy or 'fcgi' for FastCGI proxy. Default is 'http'",
    "proxyPath": "Optional. If set, only requests matching this path prefix will be proxied. Other requests will be served as static files",
    "cgiPath": "Path prefix where CGI scripts are located (e.g., '/cgi-bin'). Scripts in this path will be executed",
    "phpProxyFCGI": "TCP address for PHP FastCGI (e.g., '127.0.0.1:9000')",
    "proxyUnixSocket": "Unix socket path for proxy connections (e.g., '/var/run/app.sock')",
    "user": "System user to run processes as (for CGI execution)",
    "group": "System group to run processes as (for CGI execution)",
    "locations": "Array of location blocks. Each location matches requests by path prefix or regex. Handler types: 'proxy', 'cgi', 'php', 'static'",
    "matchType": "Location match type: 'prefix' (default, matches by path prefix, longest wins), 'regex' (matches by regex pattern), 'regexCaseInsensitive' (case-insensitive regex). Regex matches have higher priority than prefix matches.",
    "listen": "Array of ports that a virtual host should listen on. If empty, virtual host is available on all ports. Global 'listen' ports apply to all virtual hosts. Virtual host 'listen' ports restrict that virtual host to specific ports."
  },
  "multiPortExamples": [
    {
      "name": "Multiple Global Ports",
      "description": "Server listens on multiple ports globally",
      "config": {
        "listen": ["80", "8080", "8888"],
        "virtualHosts": [
          {
            "serverName": "example.com",
            "documentRoot": "/var/www/example.com"
          }
        ]
      }
    },
    {
      "name": "Virtual Host on Specific Port",
      "description": "Different virtual hosts on different ports",
      "config": {
        "virtualHosts": [
          {
            "serverName": "app1.example.com",
            "listen": ["8080"],
            "documentRoot": "/var/www/app1",
            "locations": [
              {
                "path": "\\.php$",
                "matchType": "regexCaseInsensitive",
                "handler": "proxy",
                "proxyUnixSocket": "/run/app1-fcgi.sock",
                "proxyType": "fcgi"
              }
            ]
          },
          {
            "serverName": "app2.example.com",
            "listen": ["8081"],
            "documentRoot": "/var/www/app2",
            "locations": [
              {
                "path": "\\.php$",
                "matchType": "regexCaseInsensitive",
                "handler": "proxy",
                "proxyUnixSocket": "/run/app2-fcgi.sock",
                "proxyType": "fcgi"
              }
            ]
          },
          {
            "serverName": "api.example.com",
            "listen": ["9090"],
            "documentRoot": "/var/www/api",
            "locations": [
              {
                "path": "/",
                "handler": "proxy",
                "proxyUnixSocket": "/var/run/api.sock",
                "proxyType": "http"
              }
            ]
          }
        ]
      }
    },
    {
      "name": "Virtual Host on Multiple Ports",
      "description": "Single virtual host accessible on multiple ports",
      "config": {
        "virtualHosts": [
          {
            "serverName": "example.com",
            "listen": ["80", "8080", "8888"],
            "documentRoot": "/var/www/example.com/public_html",
            "locations": [
              {
                "path": "\\.php$",
                "matchType": "regexCaseInsensitive",
                "handler": "proxy",
                "proxyUnixSocket": "/run/php-fpm.sock",
                "proxyType": "fcgi"
              }
            ]
          }
        ]
      }
    },
    {
      "name": "Mixed Port Configuration",
      "description": "Some virtual hosts on specific ports, others on all ports",
      "config": {
        "listen": ["80"],
        "virtualHosts": [
          {
            "serverName": "default.example.com",
            "documentRoot": "/var/www/default",
            "listen": []
          },
          {
            "serverName": "admin.example.com",
            "listen": ["8080"],
            "documentRoot": "/var/www/admin"
          },
          {
            "serverName": "api.example.com",
            "listen": ["9090"],
            "documentRoot": "/var/www/api",
            "locations": [
              {
                "path": "/",
                "handler": "proxy",
                "proxyUnixSocket": "/var/run/api.sock",
                "proxyType": "http"
              }
            ]
          }
        ]
      }
    }
  ]
}