Caddy Static File Server Configuration

Compression

To add gzip encoding support :

:80 {
  root * /srv/www
  file_server
  encode zstd, gzip 
}

Basic Site Configuration Approaches

1. Domain-Based Approach

site.example.com {
    # Configuration here
}
  • Automatically handles HTTP/HTTPS
  • Cleaner syntax
  • Automatic SSL certificate management
  • Best for simple, single-domain setups

2. Port-Based Approach

:80 {
    @site1 host site.example.com
    handle @site1 {
        # Configuration here
    }
}
  • More flexible for complex setups
  • Better for multiple domains with shared configurations
  • Explicit port control
  • Requires separate HTTPS configuration

Static vs General File Handling

Static Files

  • Files that don't change frequently (CSS, JS, images, fonts)
  • Suitable for aggressive caching
  • Served directly from disk
  • Typically matched by file extensions
  • Example extensions: .css, .js, .jpg, .png, .woff2

General Files

  • Any type of file
  • May be dynamic
  • Might need processing
  • Less aggressive caching
  • No specific extension matching

Caching Configuration

Client-Side Caching

header @static {
    Cache-Control "public, max-age=604800, must-revalidate"
}
  • Controlled via Cache-Control headers
  • Tells browsers how long to cache content
  • Common durations:
    • 1 week: 604800 seconds
    • 1 month: 2592000 seconds

Server-Side Caching

  • Optional in Caddy
  • Used for reducing server load
  • Not necessary for basic static file serving
  • Beneficial for dynamic content

Complete Configuration Example

:80 {
    # Global compression
    encode zstd gzip

    # Security headers
    header {
        Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self'; font-src 'self'; object-src 'none'"
    }

    # Static file handling
    @static {
        file
        path *.css *.js *.jpg *.jpeg *.png *.gif *.ico *.svg *.woff *.woff2
    }
    handle @static {
        header Cache-Control "public, max-age=604800, must-revalidate"
    }

    # Site configurations
    @site1 host site1.example.com
    handle @site1 {
        root * /path/to/site1
    }

    # Global file server
    file_server
}

Best Practices

  1. Header Order

    • Place global headers before handling directives
    • Security headers should be defined early in the configuration

  2. File Serving

    • Use a single global file_server directive when possible
    • Only specify roots in site-specific handlers

  3. Compression

    • Apply compression globally using encode zstd gzip
    • Let Caddy handle compression automatically

  4. Security

    • Always include Content Security Policy (CSP) headers
    • Use appropriate Cache-Control directives
    • Consider additional security headers as needed

  5. Caching Strategy

    • Use client-side caching for static assets
    • Consider server-side caching only if needed
    • Include must-revalidate for better cache control

Common Issues

  1. CSS/JS Not Loading

    • Check CSP headers
    • Verify file permissions
    • Confirm correct file paths
    • Ensure style-src and script-src are properly configured

  2. Caching Issues

    • Verify Cache-Control header syntax
    • Check browser developer tools
    • Clear browser cache during testing

  3. Multiple Site Configuration

    • Use appropriate matching based on hosts
    • Maintain correct root paths
    • Keep shared configurations at the global level

Sources

↑ Back to the top