Rebranding

Customize Surfly’s error pages by creating branded templates and configuring systemd service overrides. Three services can be customized: HAProxy, Varnish, and Proxy.

Setup

Create the error templates directory:

mkdir -p ~/surfly/error_templates/

HAProxy Service

HAProxy serves HTTP error responses and requires templates in HTTP response format.

Inspect Default Templates

First, examine the existing templates to understand their structure:

podman exec -it ss-haproxy cat /app/responses/haproxy.server_unavailable.http

Default templates look like this:

HTTP/1.0 503 Service Unavailable
Cache-Control: no-cache
Connection: close
Content-Type: text/html

<html><body><h1>503 Service Unavailable</h1>
The server is temporarily unable to handle the request
</body></html>

Create HAProxy Error Templates

Create branded versions of the error templates. Each template must include HTTP headers followed by HTML content.

Create ~/surfly/error_templates/haproxy.server_unavailable.http with this content:

HTTP/1.0 503 Service Unavailable
Cache-Control: no-cache
Connection: close
Content-Type: text/html

<!DOCTYPE html>
<html>
<head>
    <title>Your Brand - Service Unavailable</title>
    <style>
        body {
            font-family: Arial, sans-serif;
            text-align: center;
            padding: 50px;
            background-color: #f8f9fa;
        }
        h1 { color: #dc3545; }
        .brand-logo { width: 200px; margin-bottom: 20px; }
    </style>
</head>
<body>
    <h1>503 Service Unavailable</h1>
    <p>Our service is temporarily unavailable. We're working to restore it quickly.</p>
    <p>Please try again in a few minutes.</p>
</body>
</html>

Create ~/surfly/error_templates/haproxy.invalid_subdomain.http with this content:

HTTP/1.0 501 Not Implemented
Cache-Control: no-cache
Connection: close
Content-Type: text/html

<!DOCTYPE html>
<html>
<head>
    <title>Your Brand - Invalid Subdomain</title>
    <style>
        body {
            font-family: Arial, sans-serif;
            text-align: center;
            padding: 50px;
            background-color: #f8f9fa;
        }
        h1 { color: #6c757d; }
    </style>
</head>
<body>
    <h1>501 Invalid Subdomain</h1>
    <p>The subdomain you requested is not valid or does not exist.</p>
    <p>Please check the URL and try again.</p>
</body>
</html>

Available HAProxy Templates

You can customize any of these templates:

haproxy.invalid_multiserver.http
haproxy.invalid_method.http
haproxy.robots.txt.http
haproxy.security.txt.http
haproxy.sureroute-test-object.html.http
haproxy.server_unavailable.http
haproxy.too_many_requests.http
haproxy.invalid_server_name.http
haproxy.invalid_subdomain.http

Configure HAProxy Override

Create the systemd override to mount your custom templates:

mkdir -p ~/.config/containers/systemd/ss-haproxy.container.d/

Create ~/.config/containers/systemd/ss-haproxy.container.d/20-rebranding.conf with this content:

[Container]
Volume=~/surfly/error_templates/haproxy.server_unavailable.http:/app/responses/haproxy.server_unavailable.http
Volume=~/surfly/error_templates/haproxy.invalid_subdomain.http:/app/responses/haproxy.invalid_subdomain.http

Varnish Service

Varnish serves HTML error pages for caching-related errors.

Inspect Default Template

podman exec -it ss-varnish cat /app/varnish.server_unavailable.html

Default Varnish template looks like this:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<body>
<div>
    <h1>503 Service Unavailable</h1>
    <p>The server is temporarily unable to handle the request</p>
    <p>Varnish cache server</p>
</div>
</body>
</html>

Create Varnish Error Template

Create ~/surfly/error_templates/service_unavailable.html with this content:

<!DOCTYPE html>
<html>
<head>
    <title>Your Brand - Service Unavailable</title>
    <meta charset="utf-8">
    <style>
        body {
            font-family: Arial, sans-serif;
            text-align: center;
            padding: 50px;
            background-color: #f8f9fa;
        }
        .container {
            max-width: 600px;
            margin: 0 auto;
            background: white;
            padding: 40px;
            border-radius: 8px;
            box-shadow: 0 2px 10px rgba(0,0,0,0.1);
        }
        h1 { color: #dc3545; }
        .brand-logo { width: 200px; margin-bottom: 20px; }
    </style>
</head>
<body>
    <div class="container">
        <h1>Service Temporarily Unavailable</h1>
        <p>Our service is currently undergoing maintenance.</p>
        <p>We'll be back shortly. Thank you for your patience.</p>
    </div>
</body>
</html>

Configure Varnish Override

Create the systemd override:

mkdir -p ~/.config/containers/systemd/ss-varnish.container.d/

Create ~/.config/containers/systemd/ss-varnish.container.d/20-rebranding.conf with this content:

[Container]
Volume=~/surfly/error_templates/service_unavailable.html:/app/varnish.server_unavailable.html

Proxy Service

The Proxy service handles session management and serves session-related error pages.

Inspect Default Template

podman exec -it ss-proxy cat /app/templates/session_not_found.tpl

Default Proxy template looks like this:

<html>
<body>
    <h1>404 Session Not Found</h1>
</body>
</html>

Create Proxy Error Template

Create ~/surfly/error_templates/session_not_found.html with this content:

<!DOCTYPE html>
<html>
<head>
    <title>Your Brand - Session Not Found</title>
    <meta charset="utf-8">
    <style>
        body {
            font-family: Arial, sans-serif;
            text-align: center;
            padding: 50px;
            background-color: #f8f9fa;
        }
        .error-container {
            max-width: 500px;
            margin: 0 auto;
            background: white;
            padding: 40px;
            border-radius: 8px;
            box-shadow: 0 2px 10px rgba(0,0,0,0.1);
        }
        h1 { color: #ffc107; }
        .action-button {
            background-color: #007bff;
            color: white;
            padding: 12px 24px;
            text-decoration: none;
            border-radius: 6px;
            display: inline-block;
            margin-top: 20px;
            transition: background-color 0.3s;
        }
        .action-button:hover {
            background-color: #0056b3;
        }
    </style>
</head>
<body>
    <div class="error-container">
        <h1>Session Not Found</h1>
        <p>The requested session could not be found or has expired.</p>
        <p>This may happen if the session was inactive for too long.</p>
        <a href="/" class="action-button">Start New Session</a>
    </div>
</body>
</html>

Configure Proxy Override

Create the systemd override:

mkdir -p ~/.config/containers/systemd/ss-proxy.container.d/

Create ~/.config/containers/systemd/ss-proxy.container.d/20-rebranding.conf with this content:

[Container]
Volume=~/surfly/error_templates/session_not_found.html:/app/templates/session_not_found.tpl

Apply Changes

After creating your templates and override configurations:

# Reload systemd configuration
systemctl --user daemon-reload

# Restart services to apply new templates
systemctl --user restart ss-haproxy ss-varnish ss-proxy