Improve docs for custom error pages using Docker backend.

[shankie-codes]

Do you want to request a feature or report a bug?

feature

What did you do?

Configured custom error pages according to Docker backend instructions, here

What did you expect to see?

Expected to see requests for erroring back-ends being re-routed to a separate back-end that servers custom error pages.

What did you see instead?

There are three issues here, two of which are simple updates to docs (I'll submit a pull request), but the third I'm unable to solve, and after reviewing the docs and source, I'm lead to think is a bug. So here's what I'm proposing:

1. The docs here need clarifying. One, they need some examples, showing that, most commonly, <name> should == networks, and second, if you link through to the Custom Error Pages docs, it gives the error name as network (i.e. frontends.website.errors.network), when it should be frontends.website.errors.networks (plural)
2. The docs should explicitly mention that this feature is available only in 1.6 and above – if you pull traefik:latest at the moment, you don't get this version
3. If you've resolved (1) and (2) above, and set up the configuration below, you get an error in your error log: level=error msg="Error Page is configured for Frontend frontend-Host-localhost-1, but either Backend error is not set or Backend URL is missing". This is either a bug, or there's additional documentation that needs to be added to show how to make this work. I've scoured the docs and the source and can't work out what's going wrong.

I'm hoping that this is acceptable as an issue rather than a support request as I'll use this as the basis for a PR for the docs once I've got it figured out. I hope this is a valuable contribution as, though I don't write golang, I care deeply about this project and want to make it easier to use for other Docker users like me!

N.B. I started this as a SO issue

Output of traefik version: (What version of Traefik are you using?)

Version:      v1.6.0-rc4
Codename:     tetedemoine
Go version:   go1.10.1
Built:        2018-04-04_01:40:48PM
OS/Arch:      linux/amd64

What is your environment & configuration (arguments, toml, provider, platform, ...)?

defaultEntryPoints = ["http"]
# [accessLog]
# logLevel = "DEBUG"

# Enable API and dashboard
[api]
  dashboard = true

[entryPoints]
[entryPoints.http]
address = ":80"

[docker]
endpoint = "unix:///var/run/docker.sock"
domain = "localhost"
watch = true
exposedbydefault = true

docker-compose.yml

version: '2'
services:
  traefik:
    image: traefik:1.6.0-rc4
    ports:
      - "80:80"
      - "8080:8080"
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./acme:/etc/traefik/acme/
      - ./traefik.toml:/etc/traefik/traefik.toml
  error:
    image: kitematic/hello-world-nginx
    ports: 
      - "80"
    volumes:
      - ./html:/website_files
    labels:
      - "traefik.backend=error"
      - "traefik.port=80"
      - "traefik.frontend.rule=Host:error.localhost"
      - "traefik.enable=true"
  hello:
    image: kitematic/hello-world-nginx
    ports: 
      - "80"
    depends_on:
      - "error"
    labels:
      - traefik.backend=hello
      - traefik.backend.url=http://hello
      - traefik.port=801
      - traefik.frontend.rule=Host:localhost
      - traefik.enable=true
      - traefik.frontend.errors.networks.status=[500-599]
      - traefik.frontend.errors.networks.backend=error
      - traefik.frontend.errors.networks.query=/500s.html

[ldez]

1. <name> is an arbitrary name, it's not network or networks but every name you want.

2. the feature 'error pages' is available since 1.5 for the file provider. The support for docker will be available in 1.6. If an option is not described in the documentation for a provider, the feature is not available for that provider. https://docs.traefik.io/v1.5/configuration/backends/docker/#on-containers

3. https://docs.traefik.io/v1.5/configuration/commons/#custom-error-pages

Custom error pages are easiest to implement using the file provider.
For dynamic providers, the corresponding template file needs to be customized accordingly and referenced in the Traefik configuration.

Note: The behavior will be change with #3138.

FYI v1.6 is in the release candidate phase.

[shankie-codes]

Whoa, thanks for the comprehensive reply @ldez .

If I could comment on each of the three:

1. Ok, cool. But if that's the case, why is there anything at all? It would be worth the docs explaining what this <name> property does
2. Hmm yes I see your point, but if you come to Traefik docs by Google search results, it's not always obvious which verion you're looking at. I think that a little available from v.1.6, where relevant, would be nice
3. Ok, and that's the crux of my issue! Ok, great. Looking forward to that being merged. I really think it'll be an amazing feature.

Thanks!

[traefiker]

Closed by #3138.

[shankie-codes]

Hey @ldez thanks for this amazing stuff.

If I force an 502 by having a port mismatch, such as:

version: '2'
services:
  ...
  hello:
    image: kitematic/hello-world-nginx
    ports: 
      - "80"
    depends_on:
      - "error"
    labels:
      - traefik.backend=hello
      - traefik.port=801
      - traefik.frontend.rule=Host:localhost
      - traefik.enable=true
      - traefik.frontend.errors.network.status=500-599
      - traefik.frontend.errors.network.backend=error
      - traefik.frontend.errors.network.query=/500s.html

It now renders the page at http://error/500.hmtl. This is good. But, for some reason with this configuration, if I change the yaml so that the port mismatch is resolved (e.g. my container exposes :80 and Traefik is looking for :80) and leave the traefik.frontend.errors... service labels, it send me the contents of http://hello as a gzip of the html that should have been at that route. Any idea why that might be?

[shankie-codes]

Hmm well thinking about this more it's likely to be a headers problem... but why would adding those labels set different headers?

[shankie-codes]

This may be related to #421 as the Kitematic hello image uses nginx. In switching to an Apache image (or indeed a standard nginx image, not the kitematic one), it works fine.

Nothing else to do here I reckon. Thanks for the commits @ldez – it's made my weekend! 🎉

[shankie-codes]

Hey @ldez . Apologies if this is more of a support request, but I thought I'd add it here as this feature is still under RC status and could well be a bug.

With the above configuation, if I change my query to be traefik.frontend.errors.network.query=/{status}.html, it always returns the root of the site served by the error backend, rather than going to 502.html etc. as appropriate.

Any ideas? Feel free to tell me that this is a support question and to ask on Slack.

[ldez]

@shankie-san could you go on Slack? I will help you.