# Configuration Guide

## Configuration Overview

WebServ uses an nginx-inspired configuration syntax that is both powerful and familiar. Configuration files consist of directive blocks that define server behavior.

### Configuration Structure

    # Global directives (coming soon)
    worker_processes auto;
    error_log logs/error.log;

    # Server blocks define virtual hosts
    server {
        # Server-specific directives
        listen 80;
        server_name example.com;
        root /var/www/html;

        # Location blocks define URI-specific behavior
        location / {
            # Location-specific directives
            try_files $uri $uri/ =404;
        }

        location /api/ {
            proxy_pass http://backend;
        }
    }

💡 Note: Comments start with `#` and continue to the end of the line. Directives end with semicolons `;` and blocks are enclosed in braces `{}`.

## Server Directives

Server directives define the behavior of virtual hosts and are placed within `server {}` blocks.

Directive | Syntax | Description
--- | --- | ---
`listen` | `listen port [ssl];` | Specifies the port to listen on, optionally with SSL
`server_name` | `server_name name ...;` | Defines server names for virtual hosting
`root` | `root path;` | Sets the document root directory
`index` | `index file ...;` | Defines default files to serve for directories
`error_page` | `error_page code ... uri;` | Defines custom error pages for HTTP status codes
`client_max_body_size` | `client_max_body_size size;` | Maximum allowed size of client request body

### Listen Directive Examples

    # Basic HTTP server
    listen 80;

    # HTTPS server
    listen 443 ssl;

    # Specific interface
    listen 192.168.1.10:8080;

    # IPv6
    listen [::]:80;

### Server Name Examples

    # Exact match
    server_name example.com;

    # Multiple names
    server_name example.com www.example.com;

    # Wildcard
    server_name *.example.com;

    # Regular expression
    server_name ~^www\.(.+)$;

## Location Directives

Location blocks define how to process requests for specific URIs and are placed within `server {}` blocks.

### Location Matching

    # Exact match
    location = /favicon.ico {
        expires 1y;
    }

    # Prefix match
    location /images/ {
        expires 7d;
    }

    # Regular expression (case-sensitive)
    location ~ \.(jpg|jpeg|png|gif)$ {
        expires 1M;
    }

    # Regular expression (case-insensitive)
    location ~* \.(css|js)$ {
        expires 1y;
    }

Directive | Syntax | Description
--- | --- | ---
`try_files` | `try_files file ... uri;` | Tries files in order, falls back to URI
`alias` | `alias path;` | Maps location to a different path
`return` | `return code [text];` | Returns HTTP response with status code
`rewrite` | `rewrite regex replacement;` | Rewrites URI using regular expressions
`autoindex` | `autoindex on|off;` | Enables/disables directory listing
`expires` | `expires time;` | Sets cache expiration headers

## Configuration Examples

### Static Website

    server {
        listen 80;
        server_name mysite.com www.mysite.com;
        root /var/www/mysite;
        index index.html index.htm;

        # Cache static assets
        location ~* \.(css|js|jpg|jpeg|png|gif|ico|svg)$ {
            expires 1y;
            add_header Cache-Control "public, immutable";
        }

        # Security headers
        add_header X-Frame-Options "SAMEORIGIN";
        add_header X-Content-Type-Options "nosniff";
        add_header X-XSS-Protection "1; mode=block";

        # Custom error pages
        error_page 404 /404.html;
        error_page 500 502 503 504 /50x.html;
    }

### API Server with Reverse Proxy

    server {
        listen 80;
        server_name api.example.com;

        # API endpoints
        location /v1/ {
            proxy_pass http://127.0.0.1:3000;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;

            # CORS headers
            add_header Access-Control-Allow-Origin "*";
            add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS";
            add_header Access-Control-Allow-Headers "Content-Type, Authorization";
        }

        # Handle preflight requests
        location / {
            if ($request_method = 'OPTIONS') {
                add_header Access-Control-Allow-Origin "*";
                add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS";
                add_header Access-Control-Allow-Headers "Content-Type, Authorization";
                add_header Content-Length 0;
                return 204;
            }
        }
    }

### Multi-Domain Hosting

    # Main website
    server {
        listen 80;
        server_name example.com www.example.com;
        root /var/www/example.com;
        index index.html;

        location / {
            try_files $uri $uri/ =404;
        }
    }

    # Blog subdomain
    server {
        listen 80;
        server_name blog.example.com;
        root /var/www/blog;
        index index.html;

        # WordPress-style permalinks
        location / {
            try_files $uri $uri/ /index.php?$args;
        }
    }

    # File sharing subdomain
    server {
        listen 80;
        server_name files.example.com;
        root /var/www/files;

        # Enable directory browsing
        location / {
            autoindex on;
            autoindex_exact_size off;
            autoindex_localtime on;
        }

        # Restrict access to sensitive files
        location ~ /\. {
            deny all;
        }
    }

### Development Server

    server {
        listen 8080;
        server_name localhost;
        root ./www;
        index index.html;

        # Disable caching for development
        expires -1;
        add_header Cache-Control "no-cache, no-store, must-revalidate";
        add_header Pragma "no-cache";

        # Enable directory listing
        autoindex on;

        # Detailed error pages
        error_page 404 /dev-404.html;

        # Hot reload support
        location /ws {
            proxy_pass http://127.0.0.1:3001;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
        }
    }

## Best Practices

### Security

- Always set appropriate security headers
- Restrict access to sensitive files and directories
- Use HTTPS in production environments
- Implement rate limiting for API endpoints
- Validate and sanitize all input

    # Security headers example
    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";
    add_header X-XSS-Protection "1; mode=block";
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains";

    # Hide server information
    server_tokens off;

    # Restrict sensitive files
    location ~ /\.(ht|git|svn) {
        deny all;
    }

### Performance

- Set appropriate cache headers for static content
- Use gzip compression for text-based files
- Optimize file serving with sendfile
- Configure proper keepalive settings
- Use CDN for static assets in production

    # Performance optimizations
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    keepalive_timeout 65;

    # Gzip compression
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_types text/plain text/css application/json application/javascript;

### Organization

- Use separate configuration files for different sites
- Group related directives together
- Comment complex configurations
- Use consistent indentation and formatting
- Version control your configuration files

⚠️ Important: Always test configuration changes in a development environment before applying them to production. Use `webserv -t config.conf` to validate syntax.

Need more help? Check out the Getting Started guide or API Reference.