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)
  • Error pages are configured to be excluded from search engine indexing (using meta tags and HTTP headers) to
    prevent SEO issues on your website
  • HTML content (including CSS, SVG, and JS) is minified on the fly
  • 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:

[!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).

🔌 Integrations with Traefik, Nginx, Kubernetes (and more)

🚀 Kubernetes (K8s) & Ingress Traefik

There are various ways to set up “error pages” in Kubernetes with Traefik. One of the most common scenarios is when
you already have Traefik installed as an Ingress Controller with all the necessary CRDs. In this case, you still
need to install the “error pages” as a separate service, register a middleware that will use it, and apply this
middleware to all relevant routers.

> To install Traefik using Helm, you may add the following lines to your Chart.yaml file:
>
> yaml > dependencies: > - name: traefik > version: 34.1.0 # change to the latest version > repository: https://helm.traefik.io/traefik >

I prefer to install each component in a separate namespace and use Helm to manage the installation process. So
before we begin, let’s define the following settings in the values.yaml file:

yaml errorPages: enabled: true appName: error-pages namespace: error-pages version: 3.3.1 # https://github.com/tarampampam/error-pages/releases themeName: shuffle

Next, create the following Helm chart templates:

yaml # file: error-pages/namespace.yaml {{ with .Values.errorPages }} {{- if .enabled }} apiVersion: v1 kind: Namespace metadata: {name: "{{ .namespace }}"} {{- end }} {{- end }}

yaml # file: error-pages/deployment.yaml {{ with .Values.errorPages }} {{- if .enabled }} apiVersion: apps/v1 kind: Deployment metadata: name: "{{ .appName }}" namespace: {{ .namespace }} labels: {app: "{{ .appName }}"} spec: replicas: 1 selector: {matchLabels: {app: "{{ .appName }}"}} template: metadata: {labels: {app: "{{ .appName }}"}} spec: automountServiceAccountToken: false containers: - name: "{{ .appName }}" image: "ghcr.io/tarampampam/error-pages:{{ .version | default "latest" }}" env: - {name: TEMPLATE_NAME, value: "{{ .themeName | default "app-down" }}"} securityContext: runAsNonRoot: true runAsUser: 10001 runAsGroup: 10001 readOnlyRootFilesystem: true ports: - {name: http, containerPort: 8080, protocol: TCP} livenessProbe: httpGet: {port: http, path: /healthz} periodSeconds: 10 readinessProbe: httpGet: {port: http, path: /healthz} periodSeconds: 10 resources: limits: {memory: 64Mi, cpu: 200m} # change if needed requests: {memory: 16Mi, cpu: 20m} {{- end }} {{- end }}

yaml # file: error-pages/service.yaml {{ with .Values.errorPages }} {{- if .enabled }} apiVersion: v1 kind: Service metadata: name: {{ .appName }}-service namespace: {{ .namespace }} labels: {app: "{{ .appName }}"} spec: type: ClusterIP selector: {app: "{{ .appName }}"} ports: [{name: http, protocol: TCP, port: 8080, targetPort: 8080}] {{- end }} {{- end }}

yaml # file: error-pages/middleware.yaml {{ with .Values.errorPages }} {{- if .enabled }} apiVersion: traefik.io/v1alpha1 kind: Middleware metadata: name: {{ .appName }} namespace: {{ .namespace }} spec: # https://doc.traefik.io/traefik/routing/providers/kubernetes-crd/#kind-middleware errors: status: ["401", "403", "404", "500-599"] service: {name: "{{ .appName }}-service", port: 8080} query: "/{status}.html" {{- end }} {{- end }}

If everything was configured correctly, you should see the new middleware in your Traefik dashboard after applying
updated Helm chart:



Since our middleware is in a separate namespace, and in Traefik >=2.5 cross-namespace references for resources
like middlewares are restricted by default, we need to enable this feature. To do so, add the following lines to
your Traefik Helm chart values:

diff traefik: # ... - globalArguments: [] + globalArguments: ["--providers.kubernetescrd.allowCrossNamespace=true"] # ...

Now, you can apply the middleware to the necessary ingress routes:

diff apiVersion: traefik.io/v1alpha1 kind: IngressRoute metadata: name: some-app-http namespace: some-app spec: # https://doc.traefik.io/traefik/routing/providers/kubernetes-crd/#kind-ingressroute entryPoints: [websecure] routes: - match: Host(`my.awesome-site.com`) && PathPrefix(`/`) services: [{name: "some-app-service", namespace: some-app, port: 8080}] + {{- with $.Values.errorPages }}{{ if .enabled }} + middlewares: [{name: "{{ .appName }}", namespace: "{{ .namespace }}"}] + {{- end }}{{ end }}

Although this approach is quite verbose, it allows for full control over the configuration. If you have a
better alternative, feel free to submit a PR!

🦾 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

CLI interface

Usage:

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

Global flags:

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:

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:

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:

🦾 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.