How to configure custom Jahia error pages

How custom error pages work

Two types:

Errors pages: HAProxy send the request to the backends and sends a custom error page depending on the return code
Maintenance pages: HAProxy immediately serves the maintenance page without even contacting the backends

For errors pages:

1. Please create a separate file for each error, giving them an ".http" extension. For example, name one of them "404.http." Here is a template you can use :

HTTP/1.1 404 Not Found
Cache-Control: no-cache
Connection: close
Content-Type: text/html

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <title>404 Not Found</title>
    </head>
    <body>
        <main>
            <h1>404 Not Found</h1>

            This is my custom 404 Not Found page!
        </main>
    </body>
</html>

ℹ️ Importing additional files alongside the HTML is not supported. The maintenance page should be a single '.html' file. External CSS and images cannot be added directly. However, you can incorporate CSS within the HTML page using the <style> tag. As for images, while we typically recommend base64 encoding, for larger images, it may be necessary to utilize a direct link instead.

2. Reach out to Jahia Support to request the upload of these error files to Jahia.

3. After the support team has successfully uploaded the files, proceed to Jahia Cloud. Navigate to the "Configuration" section, and then access the "Front End" settings. Add the following configurations:

add a new section called http-errors to define error files like:

errorfile 401 /etc/haproxy/haproxy.cfg.jahia/customer.errorpages.d/401.http
errorfile 404 /etc/haproxy/haproxy.cfg.jahia/customer.errorpages.d/404.http
errorfile 502 /etc/haproxy/haproxy.cfg.jahia/customer.errorpages.d/502.http

errors returned by HAProxy (400, 403, 405, 408, 429, 500, 502, 503, and 504) can be configured this way:

errorfiles myerrors

and errors returned by the backend only (for instance 404 or 500) can be configured this way (need to intercept the response to send a custom error page):

    errorfiles myerrors
    http-response return status 404 default-errorfiles if { status 404 }

For maintenance page:

1. Please create a file named "maintenance.html". Here is a template you can use :

<!DOCTYPE html>
<html lang="en">
<head>
   <meta charset="utf-8" />
   <title>Site Undergoing Maintenance</title>
</head>
<body>
   The site is undergoing scheduled maintenance.
</body>
</html>

2. Reach out to Jahia Support to request the upload of this maintenance page to Jahia.

3. After the support team has successfully uploaded the file, proceed to Jahia Cloud. Navigate to the "Configuration" section, and then access the "Front End" settings. Add the following configurations:

http-request return status 503 content-type text/html file /etc/haproxy/haproxy.cfg.jahia/customer.errorpages.d/maintenance.html