error-pages/README.md

CLI interface

Usage:

$ error-pages [GLOBAL FLAGS] [COMMAND] [COMMAND FLAGS] [ARGUMENTS...]

Global flags:

Name	Description	Default value	Environment variables
--log-level="…"	logging level (debug/info/warn/error)	info	LOG_LEVEL
--log-format="…"	logging format (console/json)	console	LOG_FORMAT

serve command (aliases: s, server, http)

Start HTTP server.

Usage:

$ error-pages [GLOBAL FLAGS] serve [COMMAND FLAGS] [ARGUMENTS...]

The following flags are supported:

Name	Description	Default value	Environment variables
--listen="…" (-l)	the HTTP server will listen on this IP (v4 or v6) address (set 127.0.0.1 for localhost, 0.0.0.0 to listen on all interfaces, or specify a custom IP)	0.0.0.0	LISTEN_ADDR
--port="…" (-p)	the TCP port number for the HTTP server to listen on (0-65535)	8080	LISTEN_PORT
--add-template="…"	to add a new template, provide the path to the file using this flag (the filename without the extension will be used as the template name)	[]	none
--disable-template="…"	disable the specified template by its name (useful to disable the built-in templates and use only custom ones)	[]	none
--add-http-code="…" (--add-code)	to add a new HTTP status code, provide the code and its message/description using this flag (the format should be '%code%=%message%/%description%'; the code may contain a wildcard '*' to cover multiple codes at once, for example, '4**' will cover all 4xx codes unless a more specific code is described previously)	map[]	none
--json-format="…"	override the default error page response in JSON format (Go templates are supported; the error page will use this template if the client requests JSON content type)		RESPONSE_JSON_FORMAT
--xml-format="…"	override the default error page response in XML format (Go templates are supported; the error page will use this template if the client requests XML content type)		RESPONSE_XML_FORMAT
--plaintext-format="…"	override the default error page response in plain text format (Go templates are supported; the error page will use this template if the client requests plain text content type or does not specify any)		RESPONSE_PLAINTEXT_FORMAT
--template-name="…" (-t)	name of the template to use for rendering error pages (built-in templates: app-down, cats, connection, ghost, hacker-terminal, l7, lost-in-space, noise, orient, shuffle)	app-down	TEMPLATE_NAME
--disable-l10n	disable localization of error pages (if the template supports localization)	false	DISABLE_L10N
--default-error-page="…"	the code of the default (index page, when a code is not specified) error page to render	404	DEFAULT_ERROR_PAGE
--send-same-http-code	the HTTP response should have the same status code as the requested error page (by default, every response with an error page will have a status code of 200)	false	SEND_SAME_HTTP_CODE
--show-details	show request details in the error page response (if supported by the template)	false	SHOW_DETAILS
--proxy-headers="…"	HTTP headers listed here will be proxied from the original request to the error page response (comma-separated list)	X-Request-Id,X-Trace-Id,X-Amzn-Trace-Id	PROXY_HTTP_HEADERS
--rotation-mode="…"	templates automatic rotation mode (disabled/random-on-startup/random-on-each-request/random-hourly/random-daily)	disabled	TEMPLATES_ROTATION_MODE

build command (aliases: b)

Build the static error pages and put them into a specified directory.

Usage:

$ error-pages [GLOBAL FLAGS] build [COMMAND FLAGS] [ARGUMENTS...]

The following flags are supported:

Name	Description	Default value	Environment variables
--add-template="…"	to add a new template, provide the path to the file using this flag (the filename without the extension will be used as the template name)	[]	none
--disable-template="…"	disable the specified template by its name (useful to disable the built-in templates and use only custom ones)	[]	none
--add-http-code="…" (--add-code)	to add a new HTTP status code, provide the code and its message/description using this flag (the format should be '%code%=%message%/%description%'; the code may contain a wildcard '*' to cover multiple codes at once, for example, '4**' will cover all 4xx codes unless a more specific code is described previously)	map[]	none
--disable-l10n	disable localization of error pages (if the template supports localization)	false	DISABLE_L10N
--index (-i)	generate index.html file with links to all error pages	false	none
--target-dir="…" (--out, --dir, -o)	directory to put the built error pages into	.	none

healthcheck command (aliases: chk, health, check)

Health checker for the HTTP server. The use case - docker health check.

Usage:

$ error-pages [GLOBAL FLAGS] healthcheck [COMMAND FLAGS] [ARGUMENTS...]

The following flags are supported:

Name	Description	Default value	Environment variables
--port="…" (-p)	TCP port number with the HTTP server to check	8080	LISTEN_PORT

🪂 Templates (themes)

The following templates are built-in and available for use without any additional setup:

Template	Preview
app-down
cats
connection
ghost
hacker-terminal
l7
lost-in-space
noise
orient
shuffle

Note

The "used times" counter increments when someone start the server with the specified template. Stats service does not collect any information about location, IP addresses, and so on. Moreover, the stats are open and available for everyone at error-pages.goatcounter.com. This is simply a counter to display how often a particular template is used, nothing more.