docs: update README.md

Author: mamchurovskyy

README.md

@@ -4,45 +4,106 @@
 
 # spa-to-http
 
-> World's fastest lightweight zero-configuration SPA HTTP server.
+> A zero-configuration HTTP server for built SPA bundles.
 
-Serve a built SPA bundle over HTTP with sensible defaults for caching and optional Brotli/Gzip compression. It’s designed to run cleanly in Docker and behind reverse proxies like Traefik or Cloudflare.
+`spa-to-http` serves your built frontend (`dist/`) with SPA fallback routing, cache-friendly defaults, and optional Brotli/Gzip compression.
 
-## Quick Start
+If you want to ship a static SPA quickly in Docker without writing Nginx config, this is the fast path.
+
+## Why use spa-to-http
+
+- Fast-to-deploy: run one container, mount your build folder, done.
+- Operationally simple: no custom web-server config files.
+- Lightweight runtime: small Docker image and fast startup.
+- SPA-focused defaults: sensible handling for `index.html`, hashed assets, and optional compression.
+
+## Benchmark Highlights
+
+From [`docs/benchmarks.md`](docs/benchmarks.md):
+
+- Startup readiness (100 startups): `1.358s` vs Nginx `1.514s` (`11.5%` faster)
+- Small-file throughput (0.5 KiB HTML): `80,497 req/s` vs `79,214 req/s`
+- Mid-size JS throughput (5 KiB): `66,126 req/s` vs `62,831 req/s` (`5.2%` faster)
+- Docker image size comparison in docs: `13.2 MiB` (`spa-to-http`) vs `142 MiB` (Nginx sample image)
+
+See full comparison table and source methodology in [`docs/benchmarks.md`](docs/benchmarks.md).
+
+## Get Started in 60 Seconds
 
 ```bash
 # Serve ./dist at http://localhost:8080
 docker run --rm -p 8080:8080 -v $(pwd)/dist:/code devforth/spa-to-http:latest
 ```
 
-For local (non-Docker) runs, see [Local Run (Console)](docs/getting-started.md#local-run-console).
+Open `http://localhost:8080`.
 
-## Key Features
+## Recommended: Build SPA + Runtime in One Dockerfile
 
-- Zero-configuration Docker setup for common SPA outputs
-- Small image and fast startup (Go binary)
-- Optional Brotli/Gzip compression
-- Cache-control optimized for hashed assets and index.html
-- Works with popular SPA toolchains (React, Vue, Angular, Svelte, Vite, Webpack)
+In most cases, users prefer building the SPA and serving it in one image:
+
+```dockerfile
+FROM node:20-alpine AS builder
+WORKDIR /code
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM devforth/spa-to-http:latest
+COPY --from=builder /code/dist/ .
+```
 
-## Example
+Build and run:
 
 ```bash
-# Enable Brotli and serve on a custom port
-docker run --rm -p 8082:8082 -v $(pwd)/dist:/code devforth/spa-to-http:latest --brotli --port 8082
+docker build -t my-spa .
+docker run --rm -p 8080:8080 my-spa
 ```
 
----
+## Common Copy-Paste Commands
 
-## Documentation
+### Custom port + Brotli
 
-| Guide | Description |
-|-------|-------------|
-| [Getting Started](docs/getting-started.md) | Install, build, and run | 
-| [Configuration](docs/configuration.md) | Environment variables and CLI flags |
-| [Deployment](docs/deployment.md) | Docker and reverse proxy setup |
-| [Architecture](docs/architecture.md) | Project structure and request flow |
-| [Benchmarks](docs/benchmarks.md) | spa-to-http vs Nginx |
+```bash
+docker run --rm -p 8082:8082 \
+  -v $(pwd)/dist:/code \
+  devforth/spa-to-http:latest \
+  --brotli --port 8082
+```
+
+### Basic Auth (Docker)
+
+```bash
+docker run --rm -p 8080:8080 \
+  -e BASIC_AUTH="admin:secret" \
+  -e BASIC_AUTH_REALM="SPA Server" \
+  -v $(pwd)/dist:/code \
+  devforth/spa-to-http:latest
+```
+
+### Compose / reverse proxy setup
+
+For full Docker Compose and Traefik examples, see [`docs/deployment.md`](docs/deployment.md).
+
+## Feature Snapshot
+
+- Zero-configuration Docker usage for SPA bundles
+- Optional Brotli/Gzip compression
+- Cache-control tuning (`--cache-max-age`, `--ignore-cache-control-paths`)
+- SPA mode toggle (`--spa` / `SPA_MODE`)
+- In-memory file cache (`--cache`, `--cache-buffer`)
+- Optional request logging and basic auth
+
+## Documentation Map
+
+| Need | Go to |
+|---|---|
+| Fast Docker onboarding | [`docs/getting-started.md`](docs/getting-started.md) |
+| Local development and source-based workflows | [`docs/development.md`](docs/development.md) |
+| Full flag/env reference and examples | [`docs/configuration.md`](docs/configuration.md) |
+| Deployment behind Traefik / reverse proxy | [`docs/deployment.md`](docs/deployment.md) |
+| Internal package layout and request flow | [`docs/architecture.md`](docs/architecture.md) |
+| Detailed benchmark tables and source link | [`docs/benchmarks.md`](docs/benchmarks.md) |
 
 ## License
 

docs/architecture.md

@@ -1,4 +1,4 @@
-[← Deployment](deployment.md) · [Back to README](../README.md) · [Benchmarks →](benchmarks.md)
+[← Deployment](deployment.md) · [Development](development.md) · [Back to README](../README.md) · [Benchmarks →](benchmarks.md)
 
 # Architecture
 

docs/benchmarks.md

@@ -8,10 +8,10 @@
 |---|---|---|
 | Zero-configuration | ✅ No config files, SPA serving works out of the box | ❌ Requires dedicated config file |
 | Config via env/CLI | ✅ Yes | ❌ No |
-| Docker image size | ✅ 13.2 MiB (v1.0.3) | ❌ 142 MiB (v1.23.1) |
+| Docker image size | ✅ 7.54 MiB (v1.1.1) | ❌ 142 MiB (v1.23.1) |
 | Brotli out-of-the-box | ✅ Yes | ❌ Requires module |
 
-Performance numbers from the benchmark section of this post:
+Performance numbers and benchmark setup details are from:
 `https://devforth.io/blog/deploy-react-vue-angular-in-docker-simply-and-efficiently-using-spa-to-http-and-traefik/`
 
 | | spa-to-http | Nginx |

docs/configuration.md

@@ -1,4 +1,4 @@
-[← Getting Started](getting-started.md) · [Back to README](../README.md) · [Deployment →](deployment.md)
+[← Getting Started](getting-started.md) · [Development](development.md) · [Back to README](../README.md) · [Deployment →](deployment.md)
 
 # Configuration
 

docs/deployment.md

@@ -1,4 +1,4 @@
-[← Configuration](configuration.md) · [Back to README](../README.md) · [Architecture →](architecture.md)
+[← Configuration](configuration.md) · [Development](development.md) · [Back to README](../README.md) · [Architecture →](architecture.md)
 
 # Deployment
 

docs/development.md

@@ -0,0 +1,91 @@
+[← Getting Started](getting-started.md) · [Back to README](../README.md) · [Configuration →](configuration.md)
+
+# Development
+
+This page is for contributors and local source-based workflows.
+
+## Prerequisites
+
+- Go 1.24+
+- Git
+
+## Run from Source
+
+Build and run the server directly:
+
+```bash
+cd src
+go build -o spa-to-http
+./spa-to-http --directory ../test/frontend/dist
+```
+
+Or run without building a binary:
+
+```bash
+cd src
+go run . --directory ../test/frontend/dist
+```
+
+Open `http://localhost:8080` in your browser.
+
+## Configure via CLI Flags
+
+```bash
+cd src
+go run . \
+  --directory ../test/frontend/dist \
+  --brotli \
+  --gzip \
+  --spa=true \
+  --logger \
+  --log-pretty \
+  --cache-max-age 3600 \
+  --threshold 2048
+```
+
+## Configure via Environment Variables
+
+```bash
+cd src
+ADDRESS=0.0.0.0 PORT=8080 \
+GZIP=true BROTLI=true \
+SPA_MODE=true LOGGER=true LOG_PRETTY=true \
+CACHE_MAX_AGE=3600 THRESHOLD=2048 \
+DIRECTORY=../test/frontend/dist \
+go run .
+```
+
+## Basic Auth (Console)
+
+```bash
+cd src
+go run . \
+  --directory ../test/frontend/dist \
+  --basic-auth "admin:secret" \
+  --basic-auth-realm "SPA Server"
+```
+
+## Test with `test/frontend/dist`
+
+Use the built-in fixture to verify routing, caching, and compression behavior.
+
+### Console
+
+```bash
+cd src
+go run . --directory ../test/frontend/dist
+```
+
+### Docker
+
+```bash
+docker run --rm -p 8080:8080 -v $(pwd)/test/frontend/dist:/code devforth/spa-to-http:latest
+```
+
+Open `http://localhost:8080` in your browser.
+
+## See Also
+
+- [Getting Started](getting-started.md) — Fast Docker onboarding
+- [Configuration](configuration.md) — Full options reference
+- [Architecture](architecture.md) — Package structure and request flow

docs/getting-started.md

@@ -1,71 +1,13 @@
-[Back to README](../README.md) · [Configuration →](configuration.md)
+[Back to README](../README.md) · [Development →](development.md)
 
 # Getting Started
 
 ## Prerequisites
 
-- Docker (recommended)
+- Docker
 - A built SPA bundle (for example, `dist/` from Vite, Webpack, or similar)
 
-## Local Run (Console)
-
-Build from source and run the server directly:
-
-```bash
-cd src
-go build -o spa-to-http
-./spa-to-http --directory ../test/frontend/dist
-```
-
-Or run without building a binary:
-
-```bash
-cd src
-go run . --directory ../test/frontend/dist
-```
-
-Open `http://localhost:8080` in your browser.
-
-### Configure via CLI Flags
-
-```bash
-cd src
-go run . \
-  --directory ../test/frontend/dist \
-  --brotli \
-  --gzip \
-  --spa=true \
-  --logger \
-  --log-pretty \
-  --cache-max-age 3600 \
-  --threshold 2048
-```
-
-### Configure via Environment Variables
-
-```bash
-cd src
-ADDRESS=0.0.0.0 PORT=8080 \
-GZIP=true BROTLI=true \
-SPA_MODE=true LOGGER=true LOG_PRETTY=true \
-CACHE_MAX_AGE=3600 THRESHOLD=2048 \
-DIRECTORY=../test/frontend/dist \
-go run .
-```
-
-### Basic Auth (Console)
-
-```bash
-cd src
-go run . \
-  --directory ../test/frontend/dist \
-  --basic-auth "admin:secret" \
-  --basic-auth-realm "SPA Server"
-```
-
-Full list of options is in [Configuration](configuration.md).
-
-## Serve a Local Build (Docker)
+## Run a Local Build (Docker)
 
 ```bash
 # Serve ./dist at http://localhost:8080
@@ -74,7 +16,7 @@ docker run --rm -p 8080:8080 -v $(pwd)/dist:/code devforth/spa-to-http:latest
 
 Open `http://localhost:8080` in your browser.
 
-### Basic Auth (Docker)
+## Basic Auth (Docker)
 
 ```bash
 docker run --rm -p 8080:8080 \
@@ -89,12 +31,11 @@ docker run --rm -p 8080:8080 \
 Use this pattern when you want to build the SPA and ship a small runtime image:
 
 ```dockerfile
-FROM node:20-alpine as builder
-WORKDIR /code/
-ADD package-lock.json .
-ADD package.json .
+FROM node:20-alpine AS builder
+WORKDIR /code
+COPY package*.json ./
 RUN npm ci
-ADD . .
+COPY . .
 RUN npm run build
 
 FROM devforth/spa-to-http:latest
@@ -104,35 +45,19 @@ COPY --from=builder /code/dist/ .
 Build and run:
 
 ```bash
-docker build -q . | xargs docker run --rm -p 8080:8080
-```
-
-## Test With `test/frontend/dist`
-
-Use the built-in fixture to verify routing, caching, and compression behavior.
-
-### Console
-
-```bash
-cd src
-go run . --directory ../test/frontend/dist
+docker build -t my-spa .
+docker run --rm -p 8080:8080 my-spa
 ```
 
-### Docker
-
-```bash
-docker run --rm -p 8080:8080 -v $(pwd)/test/frontend/dist:/code devforth/spa-to-http:latest
-```
-
-Open `http://localhost:8080` in your browser.
-
 ## Next Steps
 
 - Configure compression, cache settings, and ports in [Configuration](configuration.md)
 - Deploy behind Traefik or another reverse proxy in [Deployment](deployment.md)
+- For source-based local runs and contributor workflow, see [Development](development.md)
 
 ## See Also
 
+- [Development](development.md) — Local setup, source runs, and fixture usage
 - [Configuration](configuration.md) — Environment variables and CLI flags
 - [Deployment](deployment.md) — Docker and reverse proxy setup
 - [Architecture](architecture.md) — Project structure and request flow