A lightweight, zero-dependency static file server written in Go with a modern directory listing UI.

Directory Listing UI — Dark/light mode, grid/list view, file preview (image/video/audio/PDF/code), search with filter chips, batch ZIP download, keyboard navigation. See UI Guide.

Server Features:

• Four serving modes (basic / index / listing / both) + SPA mode
• Gzip compression (auto-skips binary files and Range requests)
• CORS & custom headers / TLS/HTTPS / access control
• Prometheus metrics (/metrics) / JSON logging / /healthz health check
• Dot file filtering (.env, .git, etc.)

• Go 1.26+ (for building from source)
• Docker (optional, for container deployment)
• Kubernetes v1.16+ (optional, for K8s/Helm deployment)

Recommended: OCI registry (Helm 3.8+)

helm install my-server oci://ghcr.io/somaz94/charts/static-file-server --version 0.5.0

Alternative: classic Helm repo

helm repo add static-file-server https://somaz94.github.io/static-file-server/helm-repo
helm repo update
helm install my-server static-file-server/static-file-server

See Deployment Guide for full Helm chart options and storage examples.

docker run -d \
  --name static-file-server \
  -p 8080:8080 \
  -v /path/to/files:/web:ro \
  somaz940/static-file-server:v0.5.0

git clone https://github.com/somaz94/static-file-server.git
cd static-file-server
make build
./bin/static-file-server

cat <<EOF > config.yaml
folder: /var/www
port: 8080
cors: true
show-listing: true
compression: true
hide-dot-files: true
metrics: true
EOF

./bin/static-file-server -c config.yaml

See Configuration Guide for all options and environment variables.

# With environment variables
FOLDER=./public PORT=3000 CORS=true ./bin/static-file-server

# With a config file
./bin/static-file-server -c config.yaml

Priority: Environment variables > YAML config file > Default values

See Configuration Guide for the full variable list (TLS, access control, custom headers, log format, etc.).

cmd/                    # CLI entry point (Cobra-based)
internal/config/        # Configuration loading (env > YAML > defaults)
internal/handler/       # HTTP middleware chain + directory listing
internal/server/        # HTTP/HTTPS server lifecycle
internal/version/       # Build version metadata (ldflags)
deploy/                 # Kubernetes manifests + Helmfile examples (see [deploy/README.md](deploy/README.md))
helm/                   # Helm chart (7 templates + 7 examples)
docs/                   # Documentation
hack/                   # Build/version scripts
testdata/               # Sample files for local deploy testing
.github/workflows/      # CI/CD (10 workflows)

Middleware chain (outer to inner): Metrics → Health check → Logging → Prefix → Access key → Referrer → CORS → Custom headers → Compression → Dot files → File handler

make build            # Build binary
make test             # Run all tests with race detector
make cover            # HTML coverage report
make lint             # Run golangci-lint
make deploy-all       # Build + run + smoke test (49 checks)
make cross-build      # Build for linux/darwin amd64/arm64

See Testing Guide for details.

Issues and pull requests are welcome.

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.