README.md

^{22 feb. 2022 - ⚡ Our Docker image was downloaded one MILLION times from the docker hub! ⚡
10 apr. 2023 - ⚡ Two million times from the docker hub and one million from the ghcr! ⚡}

One day you may want to replace the standard error pages of your HTTP server with something more original and pretty. That's what this repository was created for :) It contains:

• Simple error pages generator, written in Go
• Single-page error page templates with different designs (located in the templates directory)
• Fast and lightweight HTTP server
• Already generated error pages (sources can be found here, the demonstration is always accessible here)

🔥 Features list

• HTTP server written in Go, with the extremely fast FastHTTP under the hood
  • Respects the Content-Type HTTP header (and X-Format) value and responds with the corresponding format (supported formats are json and xml)
  • Writes logs in json format
  • Contains healthcheck endpoint (/healthz)
  • Contains metrics endpoint (/metrics) in Prometheus format
• Lightweight docker image (~4.6Mb compressed size), distroless and uses the unleveled user by default
• Go-template tags are allowed in the templates
• Ready for integration with Traefik (error pages customization) and Ingress-nginx
• Error pages can be embedded into your own nginx docker image
• Fully configurable (take a look at the configuration file and project Wiki)
• Distributed using docker image and compiled binary files
• Localized (🇺🇸, 🇫🇷, 🇺🇦, 🇷🇺, 🇵🇹, 🇳🇱, 🇩🇪, 🇪🇸, 🇨🇳, 🇮🇩, 🇵🇱) HTML error pages (translation process described here - other translations are welcome!)

🧩 Install

Download the latest binary file for your os/arch from the releases page or use our docker image:

Registry	Image
Docker Hub	tarampampam/error-pages
GitHub Container Registry	ghcr.io/tarampampam/error-pages

Using the latest tag for the docker image is highly discouraged because of possible backward-incompatible changes during major upgrades. Please, use tags in X.Y.Z format

💣 Or you can download already rendered error pages pack as a zip or tar.gz archive.

🛠 Usage

Please, take a look at our Wiki for the common usage stories:

• HTTP server (routes, formats, flags and environment variables)
• Pages generator (build your own error page set)
• Static error pages (extract generated static error pages from the docker image)
• Usage with nginx (include our error pages into an image with nginx)
• Usage with Traefik and local Docker Compose (it's a good starting point for the tests)
• Usage with Traefik and Docker Swarm
• Kubernetes & ingress nginx

🦾 Performance

Used hardware:

• Intel® Core™ i7-10510U CPU @ 1.80GHz × 8
• 16 GiB RAM

$ ulimit -aH | grep file
-f: file size (blocks)              unlimited
-c: core file size (blocks)         unlimited
-n: file descriptors                1048576
-x: file locks                      unlimited

$ docker run --rm -p "8080:8080/tcp" -e "SHOW_DETAILS=true" error-pages:local # in separate terminal

$ wrk --timeout 1s -t12 -c400 -d30s -s ./test/wrk/request.lua http://127.0.0.1:8080/
Running 30s test @ http://127.0.0.1:8080/
  12 threads and 400 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency    10.84ms    7.89ms 135.91ms   79.36%
    Req/Sec     3.23k   785.11     6.30k    70.04%
  1160567 requests in 30.10s, 4.12GB read
Requests/sec:  38552.04
Transfer/sec:    140.23MB

FS & memory usage stats during the test

🪂 Templates

Name	Preview
ghost
l7-light
l7-dark
shuffle
noise
hacker-terminal
cats
lost-in-space
app-down
connection
matrix
orient

Note: noise template highly uses the CPU, be careful

🦾 Contributors

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

📰 Changes log

Changes log can be found here.

👾 Support

If you find any bugs in the project, please create an issue in the current repository.

📖 License

This is open-sourced software licensed under the MIT License.