How to serve static HTML with status 503 (or 502) when web server is down?

[kotsius (Konstantine Sykiotis)]

1. Caddy version (caddy version):

2.2.1

2. How I run Caddy:

a. System environment:

Debian Buster

b. Command:

systemctl start caddy

c. Service/unit/compose file:

# caddy.service
#
# For using Caddy with a config file.
#
# Make sure the ExecStart and ExecReload commands are correct
# for your installation.
#
# See https://caddyserver.com/docs/install for instructions.
#
# WARNING: This service does not use the --resume flag, so if you
# use the API to make changes, they will be overwritten by the
# Caddyfile next time the service is restarted. If you intend to
# use Caddy's API to configure it, add the --resume flag to the
# `caddy run` command or use the caddy-api.service file instead.

[Unit]
Description=Caddy
Documentation=https://caddyserver.com/docs/
After=network.target network-online.target
Requires=network-online.target

[Service]
User=caddy
Group=caddy
ExecStart=/usr/bin/caddy run --environ --config /etc/caddy/Caddyfile
ExecReload=/usr/bin/caddy reload --config /etc/caddy/Caddyfile
TimeoutStopSec=5s
LimitNOFILE=1048576
LimitNPROC=512
PrivateTmp=true
ProtectSystem=full
AmbientCapabilities=CAP_NET_BIND_SERVICE

[Install]
WantedBy=multi-user.target

d. My complete Caddyfile or JSON config:

{
	http_port   7080
	https_port  7443
}

cdn.mywebsite.com www.mywebsite.com {
	@slashend path_regexp dir (.+)/$
	redir @slashend {http.regexp.dir.1} permanent
	reverse_proxy 10.10.1.9:9080
}

mywebsite.com {
	header strict-transport-security "max-age=63072000; includesubdomains; preload"
	redir https://www.mywebsite.com{uri} permanent
}

3. The problem I’m having:

When the upstream server (10.10.1.9 in my case) is down, I would like to serve a static HTML file with status code 503 (or alternatively 502). I have not been able to find any examples as to how this might be achieved with Caddy 2. I am new to Caddy with no experience in using it as anything other than a reverse proxy, but I believe that an example configuration would be of help to others too.

4. Error messages and/or full log output:

n/a

5. What I already tried:

I have spent over an hour searching online but could find no relevant Caddy 2 examples. The two most relevant finds are included below.

6. Links to relevant resources:

V2: Can I fail to status code 503 instead of 502?

It’s something that nginx offers, in the form of: Furthermore, it is possible to change the response code to another using the “ = response ” syntax, for example: `error_page 404 =200 /empty.gif; If that syntax worked with Caddy, I would expect something like this to work: server.example.com { reverse_proxy * 192.168.0.13:1234 error_page 502 =503 maintenance.html } or perhaps server.example.com { reverse_proxy * 192.168.0.13:1234 { error_page 502 =503 maintentance.h…

Serving maintenance page with 503 status code in Caddy

[francislavoie]

You can use the handle_errors directive for this:

handle_errors (Caddyfile directive) - Caddy Documentation

Basically it’s a separate handler chain that gets invoked when Caddy emits an error (does not get invoked if a proxy writes a valid response, even if it’s a 4xx or 5xx status, by the way).

You can use an expression matcher to only handle status 502 which is the error Caddy emits when the backend is down:

Request matchers (Caddyfile) - Caddy Documentation

[kotsius (Konstantine Sykiotis)]

Thanks for your help, Francis!

For other users, this addition to my Caddyfile seems to work:

handle_errors {
	@maintenance expression {http.error.status_code} == 502
	rewrite @maintenance maintenance.html
	root * /etc/caddy
	file_server
}