error-pages/README.md

One day, you might want to replace the standard error pages of your HTTP server or K8S cluster with something more original and attractive. That's why this repository was created :) It contains:

• A simple error page generator written in Go
• Single-page error templates (themes) with various designs (located in the templates directory) that you can customize as you wish
• A fast and lightweight HTTP server is available as a single binary file and Docker image. It includes built-in error page templates from this repository. You don't need anything except the compiled binary file or Docker image
• Pre-generated error pages (sources can be found here, and the demo is always accessible here)

🔥 Features List

• HTTP server written in Go, utilizing the extremely fast FastHTTP and in-memory caching
  • Respects the Content-Type HTTP header (and X-Format) value, responding with the corresponding format (supported formats: json, xml, and plaintext)
  • Logs written in json format
  • Contains a health check endpoint (/healthz)
  • Consumes very few resources and is suitable for use in resource-constrained environments
• Lightweight Docker image, distroless, and uses an unprivileged user by default
• Go-template tags are allowed in the templates
• Ready for integration with Traefik, Ingress-nginx, and more
• Error pages can be embedded into your own Docker image with nginx in a few simple steps
• Fully configurable
• Distributed as a 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/architecture from the releases page or use our Docker image:

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

Important

Using the latest tag for the Docker image is highly discouraged due to potential backward-incompatible changes during major upgrades. Please use tags in the X.Y.Z format.

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

🪂 Templates (themes)

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

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.

Template	Preview
app-down
cats
connection
ghost
hacker-terminal
l7
lost-in-space
noise
orient
shuffle

Note

The "used times" counter increments when someone start the server with the specified template. Stats service does not collect any information about location, IP addresses, and so on. Moreover, the stats are open and available for everyone at error-pages.goatcounter.com. This is simply a counter to display how often a particular template is used, nothing more.

🛠 Usage scenarios

HTTP server starting, utilizing either a binary file or Docker image

First, ensure you have a precompiled binary file on your machine or have Docker/Podman installed. Next, start the server with the following command:

$ ./error-pages serve
# --- or ---
$ docker run --rm -p '8080:8080/tcp' tarampampam/error-pages serve

That's it! The server will begin running and listen on address 0.0.0.0 and port 8080. Access error pages using URLs like http://127.0.0.1:8080/{page_code}.html.

To retrieve different error page codes using a static URL, use the X-Code HTTP header:

$ curl -H 'X-Code: 500' http://127.0.0.1:8080/

The server respects the Content-Type HTTP header (and X-Format), delivering responses in requested formats such as HTML, XML, JSON, and PlainText. Customization of these formats is possible via CLI flags or environment variables.

For integration with ingress-nginx or debugging purposes, start the server with --show-details (or set the environment variable SHOW_DETAILS=true) to enrich error pages (including JSON and XML responses) with upstream proxy information.

Switch themes using the TEMPLATE_NAME environment variable or the --template-name flag; available templates are detailed in the readme file below.

Tip

Use the --rotation-mode flag or the TEMPLATES_ROTATION_MODE environment variable to automate theme rotation. Available modes include random-on-startup, random-on-each-request, random-hourly, and random-daily.

To proxy HTTP headers from requests to responses, utilize the --proxy-headers flag or environment variable (comma-separated list of headers).

🚀 Start the HTTP server with my custom template (theme)

First, create your own template file, for example my-super-theme.html:

<!DOCTYPE html>
<html lang="en">
<head>
  <title>{{ code }}</title>
</head>
<body>
  <h1>YEAH! {{ message }}: {{ description }}</h1>
</body>
</html>

And simply start the server with the following command:

$ docker run --rm \
  -v "$(pwd)/my-super-theme.html:/opt/my-template.html:ro" \
  -p '8080:8080/tcp' ghcr.io/tarampampam/error-pages:3 serve \
    --add-template /opt/my-template.html \
    --template-name my-template
# --- or ---
$ ./error-pages serve \
  --add-template /opt/my-template.html \
  --template-name my-template

And test it:

$ curl -H "Accept: text/html" http://127.0.0.1:8080/503

<!DOCTYPE html>
<html lang="en">
<head>
  <title>503</title>
</head>
<body>
  <h1>YEAH! Service Unavailable: The server is temporarily overloading or down</h1>
</body>
</html>

🚀 Generate a set of error pages using built-in or my own template

Generating a set of error pages is straightforward. If you prefer to use your own template, start by crafting it. Create a file like this:

<!DOCTYPE html>
<html lang="en">
<head>
  <title>{{ code }}</title>
</head>
<body>
  <h1>{{ message }}: {{ description }}</h1>
</body>
</html>

Save it as my-template.html and use it as your custom template. Then, generate your error pages using the command:

$ mkdir -p /path/to/output
$ ./error-pages build --add-template /path/to/your/my-template.html --target-dir /path/to/output

This will create error pages based on your template in the specified output directory:

$ cd /path/to/output && tree .
├── my-template
│   ├── 400.html
│   ├── 401.html
│   ├── 403.html
│   ├── 404.html
│   ├── 405.html
│   ├── 407.html
│   ├── 408.html
│   ├── 409.html
│   ├── 410.html
│   ├── 411.html
│   ├── 412.html
│   ├── 413.html
│   ├── 416.html
│   ├── 418.html
│   ├── 429.html
│   ├── 500.html
│   ├── 502.html
│   ├── 503.html
│   ├── 504.html
│   └── 505.html
…

$ cat my-template/403.html
<!DOCTYPE html>
<html lang="en">
<head>
  <title>403</title>
</head>
<body>
  <h1>Forbidden: Access is forbidden to the requested page</h1>
</body>
</html>

🚀 Customize error pages within your own Nginx Docker image

To create this cocktail, we need two components:

• Nginx configuration file
• A Dockerfile to build the image

Let's start with the Nginx configuration file:

# File: nginx.conf

server {
  listen      80;
  server_name localhost;

  error_page 401 /_error-pages/401.html;
  error_page 403 /_error-pages/403.html;
  error_page 404 /_error-pages/404.html;
  error_page 500 /_error-pages/500.html;
  error_page 502 /_error-pages/502.html;
  error_page 503 /_error-pages/503.html;

  location ^~ /_error-pages/ {
    internal;
    root /usr/share/nginx/errorpages;
  }

  location / {
    root  /usr/share/nginx/html;
    index index.html index.htm;
  }
}

And the Dockerfile:

FROM docker.io/library/nginx:1.27-alpine

# override default Nginx configuration
COPY --chown=nginx ./nginx.conf /etc/nginx/conf.d/default.conf

# copy statically built error pages from the error-pages image
# (instead of `ghost` you may use any other template)
COPY --chown=nginx \
     --from=ghcr.io/tarampampam/error-pages:3 \
     /opt/html/ghost /usr/share/nginx/errorpages/_error-pages

Now, we can build the image:

$ docker build --tag your-nginx:local -f ./Dockerfile .

And voilà! Let's start the image and test if everything is working as expected:

$ docker run --rm -p '8081:80/tcp' your-nginx:local

$ curl http://127.0.0.1:8081/foobar | head -n 15 # in another terminal

🚀 Usage with Traefik and local Docker Compose

Instead of thousands of words, let's take a look at one compose file:

# file: compose.yml (or docker-compose.yml)

services:
  traefik:
    image: docker.io/library/traefik:v3.1
    command:
      #- --log.level=DEBUG
      - --api.dashboard=true # activate dashboard
      - --api.insecure=true # enable the API in insecure mode
      - --providers.docker=true # enable Docker backend with default settings
      - --providers.docker.exposedbydefault=false # do not expose containers by default
      - --entrypoints.web.address=:80 # --entrypoints.<name>.address for ports, 80 (i.e., name = web)
    ports:
      - "80:80/tcp" # HTTP (web)
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    labels:
      traefik.enable: true
      # dashboard
      traefik.http.routers.traefik.rule: Host(`traefik.localtest.me`)
      traefik.http.routers.traefik.service: api@internal
      traefik.http.routers.traefik.entrypoints: web
      traefik.http.routers.traefik.middlewares: error-pages-middleware
    depends_on:
      error-pages: {condition: service_healthy}

  error-pages:
    image: ghcr.io/tarampampam/error-pages:3 # using the latest tag is highly discouraged
    environment:
      TEMPLATE_NAME: l7 # set the error pages template
    labels:
      traefik.enable: true
      # use as "fallback" for any NON-registered services (with priority below normal)
      traefik.http.routers.error-pages-router.rule: HostRegexp(`.+`)
      traefik.http.routers.error-pages-router.priority: 10
      # should say that all of your services work on https
      traefik.http.routers.error-pages-router.entrypoints: web
      traefik.http.routers.error-pages-router.middlewares: error-pages-middleware
      # "errors" middleware settings
      traefik.http.middlewares.error-pages-middleware.errors.status: 400-599
      traefik.http.middlewares.error-pages-middleware.errors.service: error-pages-service
      traefik.http.middlewares.error-pages-middleware.errors.query: /{status}.html
      # define service properties
      traefik.http.services.error-pages-service.loadbalancer.server.port: 8080

  nginx-or-any-another-service:
    image: docker.io/library/nginx:1.27-alpine
    labels:
      traefik.enable: true
      traefik.http.routers.test-service.rule: Host(`test.localtest.me`)
      traefik.http.routers.test-service.entrypoints: web
      traefik.http.routers.test-service.middlewares: error-pages-middleware

After executing docker compose up in the same directory as the compose.yml file, you can:

• Open the Traefik dashboard at traefik.localtest.me
• View customized error pages on the Traefik dashboard
• Open the nginx index page at test.localtest.me
• View customized error pages for non-existent pages and domains

Isn't this kind of magic? 😀

🚀 Kubernetes (K8s) & Ingress Nginx

Error-pages can be configured to work with the ingress-nginx helm chart in Kubernetes.

• Set the custom-http-errors config value
• Enable default backend
• Set the default backend image

controller:
  config:
    custom-http-errors: >-
      401,403,404,500,501,502,503      

defaultBackend:
  enabled: true
  image:
    repository: ghcr.io/tarampampam/error-pages
    tag: '3' # using the latest tag is highly discouraged
  extraEnvs:
  - name: TEMPLATE_NAME # Optional: change the default theme
    value: l7
  - name: SHOW_DETAILS # Optional: enables the output of additional information on error pages
    value: 'true'

🦾 Performance

Hardware used:

• 12th Gen Intel® Core™ i7-1260P (16 cores)
• 32 GiB RAM

RPS: ~180k 🔥 requests served without any errors, with peak memory usage ~60 MiB under the default configuration

Performance test details (click to expand)

$ ulimit -aH | grep file
core file size              (blocks, -c) unlimited
file size                   (blocks, -f) unlimited
open files                          (-n) 1048576
file locks                          (-x) unlimited

$ go build ./cmd/error-pages/ && ./error-pages --log-level warn serve

$ ./error-pages perftest # in separate terminal
Starting the test to bomb ONE PAGE (code). Please, be patient...
Test completed successfully. Here is the output:

Running 15s test @ http://127.0.0.1:8080/
  12 threads and 400 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency     3.54ms    4.90ms  74.57ms   86.55%
    Req/Sec    16.47k     2.89k   38.11k    69.46%
  2967567 requests in 15.09s, 44.70GB read
Requests/sec: 196596.49
Transfer/sec:      2.96GB

Starting the test to bomb DIFFERENT PAGES (codes). Please, be patient...
Test completed successfully. Here is the output:

Running 15s test @ http://127.0.0.1:8080/
  12 threads and 400 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency     4.25ms    6.03ms  74.23ms   86.97%
    Req/Sec    14.29k     2.75k   32.16k    69.63%
  2563245 requests in 15.07s, 38.47GB read
Requests/sec: 170062.69
Transfer/sec:      2.55GB

CLI interface

Usage:

$ error-pages [GLOBAL FLAGS] [COMMAND] [COMMAND FLAGS] [ARGUMENTS...]

Global flags:

Name	Description	Default value	Environment variables
--log-level="…"	Logging level (debug/info/warn/error)	info	LOG_LEVEL
--log-format="…"	Logging format (console/json)	console	LOG_FORMAT

serve command (aliases: s, server, http)

Please start the HTTP server to serve the error pages. You can configure various options - please RTFM :D.

Usage:

$ error-pages [GLOBAL FLAGS] serve [COMMAND FLAGS] [ARGUMENTS...]

The following flags are supported:

Name	Description	Default value	Environment variables
--listen="…" (-l)	The HTTP server will listen on this IP (v4 or v6) address (set 127.0.0.1/::1 for localhost, 0.0.0.0 to listen on all interfaces, or specify a custom IP)	0.0.0.0	LISTEN_ADDR
--port="…" (-p)	The TCP port number for the HTTP server to listen on (0-65535)	8080	LISTEN_PORT
--add-template="…"	To add a new template, provide the path to the file using this flag (the filename without the extension will be used as the template name)	[]	none
--disable-template="…"	Disable the specified template by its name (useful to disable the built-in templates and use only custom ones)	[]	none
--add-code="…"	To add a new HTTP status code, provide the code and its message/description using this flag (the format should be '%code%=%message%/%description%'; the code may contain a wildcard '*' to cover multiple codes at once, for example, '4**' will cover all 4xx codes unless a more specific code is described previously)	map[]	none
--json-format="…"	Override the default error page response in JSON format (Go templates are supported; the error page will use this template if the client requests JSON content type)		RESPONSE_JSON_FORMAT
--xml-format="…"	Override the default error page response in XML format (Go templates are supported; the error page will use this template if the client requests XML content type)		RESPONSE_XML_FORMAT
--plaintext-format="…"	Override the default error page response in plain text format (Go templates are supported; the error page will use this template if the client requests plain text content type or does not specify any)		RESPONSE_PLAINTEXT_FORMAT
--template-name="…" (-t)	Name of the template to use for rendering error pages (built-in templates: app-down, cats, connection, ghost, hacker-terminal, l7, lost-in-space, noise, orient, shuffle)	app-down	TEMPLATE_NAME
--disable-l10n	Disable localization of error pages (if the template supports localization)	false	DISABLE_L10N
--default-error-page="…"	The code of the default (index page, when a code is not specified) error page to render	404	DEFAULT_ERROR_PAGE
--send-same-http-code	The HTTP response should have the same status code as the requested error page (by default, every response with an error page will have a status code of 200)	false	SEND_SAME_HTTP_CODE
--show-details	Show request details in the error page response (if supported by the template)	false	SHOW_DETAILS
--proxy-headers="…"	HTTP headers listed here will be proxied from the original request to the error page response (comma-separated list)	X-Request-Id,X-Trace-Id,X-Amzn-Trace-Id	PROXY_HTTP_HEADERS
--rotation-mode="…"	Templates automatic rotation mode (disabled/random-on-startup/random-on-each-request/random-hourly/random-daily)	disabled	TEMPLATES_ROTATION_MODE
--read-buffer-size="…"	Per-connection buffer size in bytes for reading requests, this also limits the maximum header size (increase this buffer if your clients send multi-KB Request URIs and/or multi-KB headers (e.g., large cookies), note that increasing this value will increase memory consumption)	5120	READ_BUFFER_SIZE

build command (aliases: b)

Build the static error pages and put them into a specified directory.

Usage:

$ error-pages [GLOBAL FLAGS] build [COMMAND FLAGS] [ARGUMENTS...]

The following flags are supported:

Name	Description	Default value	Environment variables
--add-template="…"	To add a new template, provide the path to the file using this flag (the filename without the extension will be used as the template name)	[]	none
--disable-template="…"	Disable the specified template by its name (useful to disable the built-in templates and use only custom ones)	[]	none
--add-code="…"	To add a new HTTP status code, provide the code and its message/description using this flag (the format should be '%code%=%message%/%description%'; the code may contain a wildcard '*' to cover multiple codes at once, for example, '4**' will cover all 4xx codes unless a more specific code is described previously)	map[]	none
--disable-l10n	Disable localization of error pages (if the template supports localization)	false	DISABLE_L10N
--index (-i)	Generate index.html file with links to all error pages	false	none
--target-dir="…" (--out, --dir, -o)	Directory to put the built error pages into	.	none

healthcheck command (aliases: chk, health, check)

Health checker for the HTTP server. The use case - docker health check.

Usage:

$ error-pages [GLOBAL FLAGS] healthcheck [COMMAND FLAGS] [ARGUMENTS...]

The following flags are supported:

Name	Description	Default value	Environment variables
--port="…" (-p)	TCP port number with the HTTP server to check	8080	LISTEN_PORT

🦾 Contributors

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

👾 Support

If you encounter any bugs in the project, please create an issue in this repository.

📖 License

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