https://github.com/purarue/darker_errors
A dark-themed HTTP error page generator
https://github.com/purarue/darker_errors
html html-templates html5 nginx
Last synced: 9 months ago
JSON representation
A dark-themed HTTP error page generator
- Host: GitHub
- URL: https://github.com/purarue/darker_errors
- Owner: purarue
- License: apache-2.0
- Created: 2020-10-16T08:38:00.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-10-24T22:55:38.000Z (over 1 year ago)
- Last Synced: 2025-02-12T22:51:15.836Z (over 1 year ago)
- Topics: html, html-templates, html5, nginx
- Language: Go
- Homepage:
- Size: 57.6 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
A dark-themed HTTP error page generator.
This is purposefully minimal, it only generates static HTML. It's meant to be a fallback and replace the default blinding `nginx` error pages.
On most of my servers, I'm typically running a reverse proxy with `nginx`, but I don't want to rely on `nginx`-specific syntax, or have to recompile `nginx` with additional modules, in case I want to use these error pages with something else.
To be clear, this is not `nginx` specific, its just why I created this. [Here's me using it](https://github.com/purarue/glue/tree/master/lib/glue_web/templates/error) in a completely different web framework; since they're just static HTML files its pretty trivial to add it to any sort of framework/server.
### Install
`go install github.com/purarue/darker_errors@latest`
### Usage
This implements a small template language.
It replaces the strings:
- `STATUS_CODE` (e.g. 404)
- `STATUS_MSG` (e.g. Not Found)
With the corresponding HTTP values.
To override the default text for each page, you can use replacement directives:
- `ERROR_TITLE` (Text in ``; default: `STATUS_CODE - STATUS_MSG`
- `ERROR_HEADING` (Large Heading; default: `
STATUS_CODE
`)
- `ERROR_MSG` (Message; default: `STATUS_MSG
`)
You can also inject additional HTML by setting one of the following:
- `ERROR_HEAD` (insert HTML into the `
` tag, can be used to add additional `` or `<meta>` tags)
- `ERROR_BEFORE_HEADING` (before `ERROR_HEADING`)
- `ERROR_AFTER_HEADING` (after `ERROR_HEADING`, before `ERROR_MSG`)
- `ERROR_AFTER_MSG` (after `ERROR_MSG`)
Options:
```
-nginx-conf
generate nginx configuration for mapping static html files
-output-dir string
output directory for *.html files (default "error_html")
```
Any additional positional arguments to `darker_errors` are interpreted as replacement directives.
### Examples:
Include website name in `<title>`:
```
darker_errors 'ERROR_TITLE:MyWebsite - STATUS_MSG'
```
If you want to modify the text for just one page, you can specify that by using the HTTP status code
Include text to go back home on a 404:
```
darker_errors '404:ERROR_AFTER_MSG:<p>Click <a href="/">here</a> to go back home.<p>`
```
To left-align text and add a bit of margin: (Modifying the CSS in general would probably require you to take a look at how the elements are positioned in the HTML in [`src/template.go`](./src/template.go)).
```
darker_errors 'ERROR_HEAD:<style>#flexbox { align-items: flex-start } #flexbox > div { margin-left: 10%; }'
```
Add a horizontal rule after the status code:
```
darker_errors 'ERROR_AFTER_HEADING:
' 'ERROR_HEAD: hr { width: 80% }'
```
Refresh the page every 2 seconds if the user encountered a `502` error:
```
darker_errors \
'502:ERROR_HEAD:' \
'502:ERROR_MSG:
This page is currently being updated...
This should be fixed in in a few seconds...
'
```
If you specify both `502:ERROR_MSG`, and `ERROR_MSG`, the `502` overwrites the generic replacement for the `502.html` page, while any other page uses the generic `ERROR_MSG` directive.
## nginx setup
Most of the time, I use nginx like:
```
# base elixir server handles everything
location / {
include /etc/nginx/pheonix_params;
proxy_pass http://localhost:8082;
}
```
.. i.e. every request which doesn't match some other location block gets sent to another 'base' webserver. That means its handles/renders its own HTTP errors, and nginx just forwards that back.
However, whenever that upstream server is down, or restarting, the user just gets the blinding `502 Bad Gateway` page. To avoid that, I typically explicitly mark at least the 502 error code in my `nginx` configuration, with the generated page from here.
To do that, this assumes you've set a `root` in a `server` directive somewhere. That can be `/var/www/html/`, or some other folder.
As an example:
```
server {
listen [::]:443 ssl ...
listen 443 ssl ...
...
root /var/www/html;
# modified from https://stackoverflow.com/a/38414723/9348376
# base pheonix server which handles most of the requests
location @pheonix {
include /etc/nginx/pheonix_params;
proxy_pass http://localhost:8082;
}
# 502 route, in case upstream server is down
error_page 502 @offline;
location @offline {
# file should be at /var/www/html/502.html
try_files /502.html 502;
}
# if the path doesn't match some static file, forward to @pheonix server
location / {
try_files $uri @pheonix;
}
}
```
In the case above, since `root` is `/var/www/html`, put the generated `502.html` file at `/var/www/html/502.html`.
If you want to use this directly with `nginx`, you could put the `error_html` folder in `/var/www/html`, and then map each error code to the HTML page, like:
```
server {
...
error_page 401 /error_html/401.html;
error_page 404 /error_html/404.html;
error_page 502 /error_html/502.html;
}
```
To generate the configuration for that, you can run:
```
darker_errors -nginx-conf
```
[`nginx` `error_page` documentation](https://nginx.org/en/docs/http/ngx_http_core_module.html#error_page)