static-server

A reusable Docker image for serving static sites and SPAs — no per-project Dockerfile needed.

Links

• Docker Hub: beeman/static-server
• GHCR: ghcr.io/beeman/static-server
• Source: github.com/beeman/static-server

What it does

Mount your dist/ folder, set some env vars, done. The server handles:

• SPA routing — unknown routes serve index.html (default on, set SPA=false to disable)
• Brotli + gzip compression — automatic, best encoding negotiated with the client
• Environment passthrough — ENV_* vars are exposed at /__/env.json and /__/env.js
• Health check — GET /__/health returns {"status":"ok"}
• HTTP Basic Auth — set HTTP_AUTH_USER and HTTP_AUTH_PASS

Quick start

services:
  web:
    image: beeman/static-server:latest
    volumes:
      - ./dist:/workspace/app:ro
    ports:
      - 9876:9876
    environment:
      - ENV_API_URL=https://api.example.com

Redirect mode

Set REDIRECT_URL to turn a container into a lightweight 301 redirect server. Useful for www. → apex domain redirects without external DNS rules.

services:
  web:
    image: beeman/static-server:latest
    volumes:
      - ./dist:/workspace/app:ro
  www:
    image: beeman/static-server:latest
    environment:
      - REDIRECT_URL=https://example.com

The path is preserved: www.example.com/about → https://example.com/about. Set REDIRECT_STATUS=302 for temporary redirects.

Performance note: The redirect adds ~800ms on the first visit due to an extra TLS handshake (two HTTPS round trips instead of one). Browsers cache 301s, so subsequent visits skip the redirect entirely. For a “someone typed www” scenario, this is fine.

History

Originally created in 2016 as a thin wrapper around superstatic. Revived and modernized in February 2026 with brotli compression, SPA mode, health endpoints, multi-arch builds, and a proper CI pipeline.