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

• header - Caddy Documentation
• header - Caddy Documentation