Custom status code pages in production

In production, status code pages are served by the Neos gateway.

If you created your own custom status code pages and want to deploy them, you'll need to create a specific docker image for the Neos gateway.

By default, the Neos gateway Docker image contains the default status code pages in the /app/status-code-pages folder and the default tenant availability pages in the /app/tenant-pages folder.

For multitenant clusters, you can override the pages used for tenant availability responses. DisabledTenantPagePath is used when a tenant is disabled by an administrator, while UnavailableTenantPagePath is used when its data persistence state is not Running. The disabled tenant page takes priority when both conditions apply. When these properties are not configured, the gateway uses /app/tenant-pages/disabled.html and /app/tenant-pages/unavailable.html respectively. The 503.html page from the status code pages directory is used when the response is not associated with a known tenant cause.

Tenant-specific pages are controlled by NEOS_TENANT_PAGES_ENABLED. The application setting defaults to true, but the standard Gateway Docker image temporarily sets it to false for backward compatibility with derived images that customize only 503.html. Set it to true in your custom image or gateway secret to enable the dedicated disabled and unavailable tenant pages. When it is false, all tenant-related 503 responses use 503.html.

To override this folder with your own implementation, you can create a dockerfile like the following :

# syntax=docker/dockerfile:1.24

ARG NEOS_VERSION=latest
FROM "harbor.hexanet.fr:8443/neos/gateway:${NEOS_VERSION}"
ARG NEOS_VERSION

COPY ./my-custom-status-code-pages-directory /app/status-code-pages
COPY ./my-custom-tenant-pages /app/tenant-pages

USER neos

Note

The COPY command will override existing files but keep files without correspondence. For example, if ./my-custom-status-code-pages-directory contains only a 403.html file, final /app/status-code-pages will still contains other status codes pages (404.html, 502.html, ...) but the default 403.html file will be replaced by the custom one.

Warning

Because the image is based on the Neos gateway image, make sure that you use the same version as the one in your deployed environment.

To override the default tenant availability pages, copy your files into the gateway image and configure their paths in the gateway environment secret using the standard .NET environment variable names:

DisabledTenantPagePath=/app/tenant-pages/disabled.html
UnavailableTenantPagePath=/app/tenant-pages/unavailable.html
NEOS_TENANT_PAGES_ENABLED=true

Important

A configured file that does not exist prevents the deployed gateway from starting. If the two variables are omitted, the default paths above are used.

In the values of the Neos Helm chart, you can then specify which image / tag / pull secret to use under the gateway section.