📝 Forums

See the forums for further discussion here Make Traefik a powerful static file server!

Features

• Basic file serving: Serves static files from a configured directory
• Directory listing control: Enable or disable directory browsing
• Custom index files: Configure which files should be used as directory index
• SPA mode: Support for Single Page Applications by redirecting 404s to index file
• Custom error pages: Configure custom error pages for 404 errors
• Cache control: Set cache control headers based on file extensions
• Full Traefik v3 compatibility: Optimized for the latest Traefik version

Configuration Options

Option	Type	Default	Description
root	String	.	Root directory to serve files from
enableDirectoryListing	Boolean	false	Whether to enable directory listing
indexFiles	Array	["index.html", "index.htm"]	List of filenames to try when a directory is requested
spaMode	Boolean	false	Redirects all not-found requests to a single page
spaIndex	String	index.html	File to serve in SPA mode
errorPage404	String	""	Path to a custom 404 error page (relative to root)
cacheControl	Map	{}	Map of file extensions to cache control values

Usage

Basic Configuration

Here is an example of a file provider dynamic configuration (given here in YAML), for basic static file serving:

Copy
# Dynamic configuration
http:
  routers:
    my-statiq-router:
      rule: host(`statiq.localhost`)
      service: noop@internal # required
      middlewares:
        - statiq

  middlewares:
    statiq:
      plugin:
        statiq:
          root: "./test_assets/sample_site/"

Advanced Configuration

Here's an example with more advanced features enabled:

Copy
# Dynamic configuration with advanced features
http:
  routers:
    my-spa-router:
      rule: host(`spa.localhost`)
      service: noop@internal
      middlewares:
        - statiq-advanced

  middlewares:
    statiq-advanced:
      plugin:
        statiq:
          root: "./test_assets/sample_site/"
          spaMode: true
          spaIndex: "index.html"
          errorPage404: "error/404.html"
          enableDirectoryListing: false
          indexFiles:
            - "index.html"
            - "default.htm"
          cacheControl:
            ".html": "max-age=3600"
            ".css": "max-age=86400"
            ".js": "max-age=86400"
            ".png": "max-age=604800"
            ".jpg": "max-age=604800"
            "*": "max-age=3600"

Local Testing

There is a docker compose.yml file to test the plugin locally:

Copy
docker compose up -d

Then, you can go to http://statiq.localhost to see the result.

Use Cases

Static Website Hosting

Perfect for hosting simple static websites with HTML, CSS, and JavaScript files.

Single Page Application (SPA) Hosting

Using the spaMode option, you can easily host React, Vue, or Angular applications that use client-side routing.

API Documentation

Host API documentation generated by tools like Swagger or Redoc directly from Traefik.

Documentation Sites

Serve markdown-based documentation sites or wikis seamlessly.