How to configure custom Jahia error pages

November 14, 2023

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>
  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 (200, 400, 403, 405, 408, 429, 500, 502, 503, and 504) can be configured this way:
    frontend frontendsite
        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):
    frontend site1
        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:

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