tarampampam/error-pages — Gitpedia

<p align="center"> <a href="https://github.com/tarampampam/error-pages#readme"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://socialify.git.ci/tarampampam/error-pages/image?description=1&font=Raleway&forks=1&issues=1&logo=https%3A%2F%2Fhsto.org%2Fwebt%2Frm%2F9y%2Fww%2Frm9ywwx3gjv9agwkcmllhsuyo7k.png&owner=1&pulls=1&pattern=Solid&stargazers=1&theme=Dark"> <img align="center" src="https://socialify.git.ci/tarampampam/error-pages/image?description=1&font=Raleway&forks=1&issues=1&logo=https%3A%2F%2Fhsto.org%2Fwebt%2Frm%2F9y%2Fww%2Frm9ywwx3gjv9agwkcmllhsuyo7k.png&owner=1&pulls=1&pattern=Solid&stargazers=1&theme=Light"> </picture> </a> </p> <p align="center"> <a href="#"><img src="https://img.shields.io/github/go-mod/go-version/tarampampam/error-pages?longCache=true&label=&logo=go&logoColor=white&style=flat-square" alt="" /></a> <a href="https://github.com/tarampampam/error-pages/actions"><img src="https://img.shields.io/github/actions/workflow/status/tarampampam/error-pages/tests.yml?branch=master&maxAge=30&label=tests&logo=github&style=flat-square" alt="" /></a> <a href="https://github.com/tarampampam/error-pages/actions"><img src="https://img.shields.io/github/actions/workflow/status/tarampampam/error-pages/release.yml?maxAge=30&label=release&logo=github&style=flat-square" alt="" /></a> <a href="https://hub.docker.com/r/tarampampam/error-pages"><img src="https://img.shields.io/docker/pulls/tarampampam/error-pages.svg?maxAge=30&label=pulls&logo=docker&logoColor=white&style=flat-square" alt="" /></a> <a href="https://hub.docker.com/r/tarampampam/error-pages"><img src="https://img.shields.io/docker/image-size/tarampampam/error-pages/latest?maxAge=30&label=size&logo=docker&logoColor=white&style=flat-square" alt="" /></a> <a href="https://github.com/tarampampam/error-pages/blob/master/LICENSE"><img src="https://img.shields.io/github/license/tarampampam/error-pages.svg?maxAge=30&style=flat-square" alt="" /></a> </p>

[!IMPORTANT]
If you were on v3 or earlier and want to upgrade to v4, check out the migration guide.

If you ended up here, chances are you would like to replace your HTTP server's default error pages with something more
original and eye-catching. That is exactly what this project is designed for - it handles this with minimal effort
on your part.

It includes:

A collection of HTTP error page designs (each with a unique look), along with the ability to use your own
custom templates
A lightweight HTTP server for serving these pages that integrates easily into your existing infrastructure
A utility for pre-rendering static HTTP error pages

Key features:

Both the HTTP server and the static generator are written in Go with zero third-party runtime dependencies
(stdlib only - hardcore mode)
- Supports HTTP/1.1 and HTTP/2 (h2c - cleartext, no TLS required)
- Returns error responses in the appropriate format (HTML, JSON, XML, plain text) based on client requests
- Gzip compression for all response formats
- HTML pages support localization (15+ languages), responsive design (mobile-friendly), and are fully
  self-contained - all styles and images are embedded directly in the HTML, without loading any external resources
- Go template-based templating engine
Ships as pre-built binaries, a minimal Docker image (rootless, scratch-based), and a ready-to-use Helm chart
for Kubernetes
Works out of the box with popular reverse proxies and ingress controllers (Nginx, Traefik, etc.)

🪂 Built-in templates

The following templates are built-in and available for use without any additional setup/files:

Template name	Preview (light)	Preview (dark)
`app-down`
`cats`
`connection`
`ghost`
`hacker-terminal`
`l7`
`lost-in-space`
`noise`
`orient`
`shuffle`
`win98`

[!NOTE]
The cats template is the only one of those that fetches resources (the actual cat pictures) from external
servers - all other templates are self-contained.

[!TIP]
If you need the pre-rendered static error pages pack, you can download it as a zip or
tar.gz archive.

🚀 Installation

Download the latest binary for your OS/architecture from the releases page, or use the Docker image:

Registry	Image
GitHub Container Registry	`ghcr.io/tarampampam/error-pages`
Quay.io (mirror)	`quay.io/tarampampam/error-pages`
Docker Hub (mirror)	`tarampampam/error-pages`

[!WARNING]
Using the latest tag for Docker images is strongly discouraged, as it may introduce backward-incompatible changes
during major upgrades. Use versioned tags in the X, X.Y, or X.Y.Z format instead.

[!IMPORTANT]
The app is distributed as two separate binaries - error-pages (HTTP server) and builder. Docker tags follow this
convention:

X.Y.Z (and X.Y, X) - includes the HTTP server

X.Y.Z-builder (and X.Y-builder, X-builder) - includes the builder and a pre-rendered error pages pack

Supported image architectures - linux/amd64, linux/arm/v7, linux/arm64, linux/ppc64le, linux/s390x.
All images are signed with Cosign using keyless signing (GitHub OIDC).

📦 Helm chart

A Helm chart for Kubernetes is included with each release (download), published on
Artifact Hub, and also available via an OCI registry (Helm v3.8+ required):

shell
helm install error-pages \
  oci://ghcr.io/tarampampam/error-pages/charts/error-pages \
  --version X.Y.Z

All supported chart values, examples, and usage instructions can be found at Artifact Hub.

Helm chart sources are located in the deploy/helm directory of the repository.

🛠 Integration guides

Standalone server or builder usage:
- 🚀 Start the HTTP server with a custom template (theme)
- 🚀 Generate error pages using built-in or custom templates
With Nginx:
- 🚀 Customize error pages in your own Nginx Docker image
- 🚀 Use Nginx as a reverse proxy with custom error pages
With Caddy:
- 🚀 Customize error pages in your own Caddy Docker image
- 🚀 Use Caddy as a reverse proxy with custom error pages
With Traefik:
- 🚀 Use Traefik with a local Docker Compose setup
With Kubernetes:

🦾 Performance

Measured on loopback (127.0.0.1), single connection, no artificial load
(wrk -t1 -c1 -d5s --latency http://127.0.0.1:8080/..., less is better):

Format	p50 (typical response time)	p90 (90% of responses complete within this time)
HTML	121 µs	262 µs
JSON	51 µs	75 µs
XML	48 µs	73 µs
Plain text	47 µs	68 µs
HTML + gzip	2.4 ms	3.1 ms
JSON + gzip	256 µs	510 µs

[!NOTE]
HTML responses are large (full rendered template, ~65 KB), which is why gzip compression takes noticeably more
time there. JSON/XML/text are compact structured responses, so they are fastest overall.

💻 Command-line usage

For detailed instructions on using the HTTP server and the static site generator, including all supported environment
variables and usage examples, check the CLI documentation.

🔍 How the server handles requests

The three most important things to understand about how the server behaves - how it determines which error page to
show, which format to return, and what request context it can expose.

How the error code is resolved

The server picks the HTTP status code from the first matching source:

Path: /404, /404.html, /404.json, /503.xml, etc.
X-Code request header
Default: --default-error-page (or DEFAULT_ERROR_PAGE, default: 404)

How the response format is determined

The response format is picked from the first matching source:

Path extension: .html, .htm, .json, .xml, .txt
Content-Type request header
X-Format request header (e.g. X-Format: application/json)
Accept request header
Default: plain text

Supported formats: HTML, JSON, XML, plain text.

Service endpoints

The following HTTP endpoints can be used for health checks, monitoring, or other purposes:

Path	Description
`/healthz`, `/health`, `/health/live`, `/live`	Liveness probe - always returns `200 OK`
`/version`	Returns `{"version":"..."}` as JSON

Response headers

Every error page response includes the following headers automatically:

Header	Value	Notes
`Content-Type`	e.g. `text/html; charset=utf-8`	Format-dependent
`Content-Length`	Response body size in bytes	Always set
`X-Robots-Tag`	`noindex, nofollow, nosnippet, noarchive`	Prevents error pages from being indexed
`Retry-After`	`120`	Only for limited set of status codes
`Content-Encoding`	`gzip`	Only when the client sends `Accept-Encoding: gzip`

Headers listed in --proxy-headers (default: X-Request-Id, X-Trace-Id, X-Correlation-Id,
X-Amzn-Trace-Id) are copied from the incoming request to the response when present.

HTTP status code of the response

By default, the server always responds with HTTP 200, even when rendering error pages. This is the correct
behavior when a reverse proxy (Nginx, Traefik, ingress-nginx) intercepts upstream error responses and replaces
only the body - the proxy itself sends the original error status code back to the client.

When error-pages is used as a direct backend - e.g. a catch-all route, a Kubernetes default backend, or
standalone testing - it must return the correct status code itself. Enable --send-same-http-code
(or env SEND_SAME_HTTP_CODE=true) to make the HTTP response status match the error code being rendered.

📝 Templating and Localization

For detailed instructions on using custom templates and localization features, see the
templating documentation.

🔧 Development

Requirements

Go 1.26+ for building from source and running tests
Optional: golangci-lint for linting
Optional: docker for testing
the Docker image locally
Optional: helm + kind + docker
for testing the Helm chart locally in Kubernetes
Optional: helm-docs for generating Helm chart documentation
Optional: wrk for benchmarking the server performance
Optional: watchexec for live reloading the server during
development

Commands:

shell
go generate -skip readme ./...            # (re)generate code, except docs
go generate ./...                         # (re)generate everything
go build ./cmd/error-pages/ && go build ./cmd/builder/ # build both binaries
go test -race ./...                       # run all tests
golangci-lint run --fix                   # lint the code and apply any available auto fixes
helm-docs -c ./deploy/helm/ -t README.tpl.md -o README.md # regenerate chart readme file

# run a live reloading server (useful for testing template changes)
watchexec -r -- go run ./cmd/error-pages/ --show-details

# run before every vibe-coding session
your_ai_tool --prompt "explain why AI Coding Agents are doing shit by default"

🧑‍🤝‍🧑 Contributors

I want to say a big thank you to everyone who contributed to this project:

🤝 Contributing & AI-assisted development

Missing a feature? Found a bug you want fixed? Pull requests are welcome - and yes, you are explicitly invited to
try implementing it with an AI coding agent.

To give the agent a fighting chance at producing something that fits this codebase, the repo ships an
AGENTS.md - a structured reference covering project layout, build commands, code style, generated
files, hard prohibitions, and the full post-change workflow. It is written for the agent. Most modern agents
pick it up automatically.

Review every single changed line yourself. Understand it. Be able to defend it in code review. If you cannot
explain why a line is there and why it is correct, do not open the PR. "The agent wrote it" is not an answer.
The author of a PR is the human who opens it, not the model (at least, I hope so).

I write my own code by hand and encourage you to do the same when you can. AI is a tool, not an excuse to skip the
thinking. Trust, but verify - and verify hard.