Files
skills/public/hanzo-static.md

4.8 KiB

Hanzo Static - Static File Server Plugin for Traefik

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-ingress.md, hanzo/hanzo-deploy.md

Overview

Hanzo Static is a Traefik plugin that serves static files (SPAs, assets) directly from the ingress controller. It replaces the need for nginx or caddy sidecars for static site serving. Configured as middleware on Traefik IngressRoutes, it serves files from a mounted volume with proper cache headers, SPA fallback routing, and gzip support.

When to use

  • Serving static-exported Next.js apps (billing, team front, etc.)
  • SPA serving with client-side routing (fallback to index.html)
  • Serving pre-built frontend assets without a Node.js runtime
  • Replacing nginx/caddy containers for static content

Hard requirements

  1. No nginx, no caddy -- use the Traefik static plugin or Hanzo Ingress middleware
  2. Gzip awareness: If serving pre-gzipped files (.html.gz), both .html and .html.gz must be updated together
  3. Cache headers: Set proper Cache-Control for immutable assets vs HTML

Quick reference

Item Value
Plugin type Traefik middleware plugin
Ingress controller Hanzo Ingress (Traefik fork)
IngressClass hanzo
SPA fallback Configurable (default: index.html)
Gzip Serves .gz files if Accept-Encoding: gzip
Cache (assets) Cache-Control: public, max-age=31536000, immutable
Cache (HTML) Cache-Control: no-cache

Architecture

Client Request
 |
Hanzo Ingress (Traefik)
 |
Static Middleware Plugin
 |
 +---+---+
 | |
Asset SPA
match fallback
 | |
Serve index.html
file (+ gzip)

Configuration

Traefik middleware (IngressRoute)

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
 name: static-serve
 namespace: hanzo
spec:
 plugin:
 static:
 root: /srv/www
 index: index.html
 spa: true
 gzip: true
 headers:
 Cache-Control: "public, max-age=31536000, immutable"
 htmlHeaders:
 Cache-Control: "no-cache"

IngressRoute with static middleware

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
 name: billing-static
 namespace: hanzo
spec:
 entryPoints:
 - websecure
 routes:
 - match: Host(`billing.hanzo.ai`)
 kind: Rule
 middlewares:
 - name: static-serve
 services:
 - name: billing
 port: 80
 tls:
 certResolver: letsencrypt

Static site deployment pattern

For static-exported apps (Next.js with output: 'export'), the typical pattern is:

apiVersion: apps/v1
kind: Deployment
metadata:
 name: billing
 namespace: hanzo
spec:
 replicas: 2
 template:
 spec:
 containers:
 - name: billing
 image: ghcr.io/hanzoai/billing:latest
 # Image contains built static files + minimal HTTP server
 ports:
 - containerPort: 80
 livenessProbe:
 httpGet:
 path: /health
 port: 80

The container image typically uses a minimal Alpine-based HTTP server or the Traefik static plugin directly.

SPA routing

For single-page applications, the plugin intercepts 404s and serves index.html instead, allowing client-side routing to work:

GET /dashboard/settings
 -> No file at /dashboard/settings
 -> SPA mode: serve /index.html
 -> Client-side router handles /dashboard/settings

Gzip handling

The plugin serves pre-gzipped files when available:

  1. Client sends Accept-Encoding: gzip
  2. Plugin checks for <file>.gz alongside <file>
  3. If .gz exists, serves it with Content-Encoding: gzip
  4. If not, serves the original file

Critical gotcha: When updating static files, you MUST update both the original and .gz versions. If you only update index.html but not index.html.gz, clients will receive the stale gzipped version.

Common patterns

Next.js static export

# Dockerfile for static site
FROM node:22-alpine AS builder
WORKDIR /app
COPY . .
RUN pnpm install && pnpm build

FROM ghcr.io/hanzoai/static:latest
COPY --from=builder /app/out /srv/www

Security headers

The static plugin adds security headers by default:

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Referrer-Policy: strict-origin-when-cross-origin

Troubleshooting

Issue Cause Solution
Old content after deploy Stale .gz file Update both .html and .html.gz
404 on client routes SPA mode not enabled Set spa: true in middleware config
Broken assets Wrong cache headers Check Cache-Control middleware config
CORS errors Missing headers Add CORS middleware before static middleware
  • hanzo/hanzo-ingress.md -- Traefik ingress controller
  • hanzo/hanzo-deploy.md -- Deployment workflow
  • hanzo/hanzo-billing.md -- Example static site deployment

Last Updated: 2026-03-23 Category: Hanzo Ecosystem Related: static, traefik, spa, nginx-replacement, cache Prerequisites: Traefik, K8s IngressRoute CRDs