error-pages/README.md

HTTP's error pages in Docker image

This repository contains:

• A very simple generator (nodejs) for HTTP error pages (like 404: Not found) with different templates supports
• Dockerfile for docker image (docker hub, ghcr.io) with generated pages and nginx as a web server

Can be used for Traefik error pages customization.

Demo

Generated pages (from the latest release) always accessible here (live preview).

Templates

Name	Preview
ghost
l7-light
l7-dark
shuffle
noise

Note: noise template highly uses the CPU, be careful

Usage

Generated error pages in our docker image permanently located in directory /opt/html/%TEMPLATE_NAME%. nginx in a container listen for 8080 (http) port.

Supported environment variables

Name	Description
TEMPLATE_NAME	(ghost by default) "default" pages template (allows to use error pages without passing theme name in URL - http://127.0.0.1/500.html instead http://127.0.0.1/ghost/500.html)

Also, you can use a special template name random - in this case template will be selected randomly.

Ready docker image

Execute in your shell:

$ docker run --rm -p "8082:8080" tarampampam/error-pages:X.X.X

Important notice: do not use the latest image tag (this is bad practice). Use versioned tag (like 1.2.3) instead.

And open in your browser http://127.0.0.1:8082/ghost/400.html.

Custom error pages for your image with nginx

You can build your own docker image with nginx and our error pages:

# 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;
  }
}

# File `Dockerfile`

FROM nginx:1.18-alpine

COPY --chown=nginx \
     ./nginx.conf /etc/nginx/conf.d/default.conf
COPY --chown=nginx \
     --from=tarampampam/error-pages:1.5.0 \
     /opt/html/ghost /usr/share/nginx/errorpages/_error-pages

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

More info about error_page directive can be found here.

Custom error pages for Traefik

Simple traefik (tested on v2.4.8) service configuration for usage in docker swarm (change with your needs):

version: '3.4'

services:
  error-pages:
    image: tarampampam/error-pages:1.5.0
    environment:
      TEMPLATE_NAME: l7-dark
    networks:
      - traefik-public
    deploy:
      placement:
        constraints:
          - node.role == worker
      labels:
        traefik.enable: 'true'
        traefik.docker.network: traefik-public
        # use as "fallback" for any non-registered services (with priority below normal)
        traefik.http.routers.error-pages-router.rule: HostRegexp(`{host:.+}`)
        traefik.http.routers.error-pages-router.priority: 10
        # should say that all of your services work on https
        traefik.http.routers.error-pages-router.tls: 'true'
        traefik.http.routers.error-pages-router.entrypoints: https
        traefik.http.routers.error-pages-router.middlewares: error-pages-middleware@docker
        traefik.http.services.error-pages-service.loadbalancer.server.port: 8080
        # "errors" middleware settings
        traefik.http.middlewares.error-pages-middleware.errors.status: 400-599
        traefik.http.middlewares.error-pages-middleware.errors.service: error-pages-service@docker
        traefik.http.middlewares.error-pages-middleware.errors.query: /{status}.html

  any-another-http-service:
    image: nginx:alpine
    networks:
      - traefik-public
    deploy:
      placement:
        constraints:
          - node.role == worker
      labels:
        traefik.enable: 'true'
        traefik.docker.network: traefik-public
        traefik.http.routers.another-service.rule: Host(`subdomain.example.com`)
        traefik.http.routers.another-service.tls: 'true'
        traefik.http.routers.another-service.entrypoints: https
        # next line is important
        traefik.http.routers.another-service.middlewares: error-pages-middleware@docker
        traefik.http.services.another-service.loadbalancer.server.port: 80

networks:
  traefik-public:
    external: true

Development

For project development we use docker-ce + docker-compose. Make sure you have them installed.

Install "generator" dependencies:

$ make install

If you want to generate error pages on your machine (after that look into the output directory):

$ make gen

If you want to preview the pages using the Docker image:

$ make preview

Changes log

Changes log can be found here.

Support

If you will find any package errors, please, make an issue in current repository.

License

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