Installing

Downloading

Cloning this project with git

Make sure to have git installed in your system.

1. Change the directory to the place where you want to clone the repository. This place must be located in the parent directory where the web root directory is, or a certain place where the error pages should be located on.

# Example
foo$ cd /var/www/html/

2. Run git clone https://github.com/TheRealOne78/error_pages.git error_pages. This will clone the repository with the directory 'error_pages'.

# Example
foo$ git clone https://github.com/TheRealOne78/error_pages.git error_pages

Downloading a zip file.

You can also download the zip file from github. Note that you can't pull new changes and you'll have to download the zip file and reconfigure every error document.

1. Download https://github.com/TheRealOne78/error_pages/archive/refs/heads/main.zip into the desired directory, where the error pages should be located. You can also use wget like in the example below:

foo$ wget https://github.com/TheRealOne78/error_pages/archive/refs/heads/main.zip

2. Uncompress the zip file in the desired directory. You can use unzip like in the example below:

foo$ unzip main.zip

Installing on HTTPD

Nginx

1. Open your 'nginx.conf' file (on POSIX systems usually available at '/etc/nginx/nginx.conf') with a text editor.
2. Add the following in your nginx.conf file:

# Error pages
error_page 404    /path/to/error/documents/error_page/404.htm;
error_page 418    /path/to/error/documents/error_page/418.htm;
error_page 500    /path/to/error/documents/error_page/500.htm;
error_page 400    /path/to/error/documents/error_page/400.htm;
error_page 401    /path/to/error/documents/error_page/401.htm;
error_page 402    /path/to/error/documents/error_page/402.htm;
error_page 403    /path/to/error/documents/error_page/403.htm;
error_page 404    /path/to/error/documents/error_page/404.htm;
error_page 405    /path/to/error/documents/error_page/405.htm;
error_page 406    /path/to/error/documents/error_page/406.htm;
error_page 407    /path/to/error/documents/error_page/407.htm;
error_page 408    /path/to/error/documents/error_page/408.htm;
error_page 409    /path/to/error/documents/error_page/409.htm;
error_page 410    /path/to/error/documents/error_page/410.htm;
error_page 411    /path/to/error/documents/error_page/411.htm;
error_page 412    /path/to/error/documents/error_page/412.htm;
error_page 413    /path/to/error/documents/error_page/413.htm;
error_page 414    /path/to/error/documents/error_page/414.htm;
error_page 415    /path/to/error/documents/error_page/415.htm;
error_page 416    /path/to/error/documents/error_page/416.htm;
error_page 417    /path/to/error/documents/error_page/417.htm;
error_page 418    /path/to/error/documents/error_page/418.htm;
error_page 421    /path/to/error/documents/error_page/421.htm;
error_page 422    /path/to/error/documents/error_page/422.htm;
error_page 423    /path/to/error/documents/error_page/423.htm;
error_page 424    /path/to/error/documents/error_page/424.htm;
error_page 425    /path/to/error/documents/error_page/425.htm;
error_page 426    /path/to/error/documents/error_page/426.htm;
error_page 428    /path/to/error/documents/error_page/428.htm;
error_page 429    /path/to/error/documents/error_page/429.htm;
error_page 431    /path/to/error/documents/error_page/431.htm;
error_page 451    /path/to/error/documents/error_page/451.htm;
error_page 500    /path/to/error/documents/error_page/500.htm;
error_page 501    /path/to/error/documents/error_page/501.htm;
error_page 502    /path/to/error/documents/error_page/502.htm;
error_page 503    /path/to/error/documents/error_page/503.htm;
error_page 504    /path/to/error/documents/error_page/504.htm;
error_page 505    /path/to/error/documents/error_page/505.htm;
error_page 506    /path/to/error/documents/error_page/506.htm;
error_page 507    /path/to/error/documents/error_page/507.htm;
error_page 508    /path/to/error/documents/error_page/508.htm;
error_page 510    /path/to/error/documents/error_page/510.htm;
error_page 511    /path/to/error/documents/error_page/511.htm;

Note that you have to replace all '/path/to/error/documents/error_page/' with the actual path that leads to the error documents. This can be easily approached with a 'replace-all' or 'multi-cursor' tool.

3. Reload nginx:

# SystemD
root# systemctl reload nginx.service

# OpenRC
root# rc-service nginx reload

# Manual
root# nginx -s reload

Any HTTPD

Edit your HTTP Daemon configuration and add the corresponding error documents.

If you have made your own HTTP Daemon, for example a python HTTP server, make sure your client handles the error response status codes with the right error documents. For example, your server needs to send the error '404 - Not Found', make sure it also sends the contents of the 404 error document in the response body:

HTTP/1.1 404 Not Found
Server: nginx/1.25.2
Date: Sun, 03 Sep 2023 13:56:48 GMT
Content-Type: text/html
Content-Length: 2791
Connection: keep-alive

{
<!DOCTYPE HTML>

<!--
  Copyright (C) 2023 TheRealOne78 <bajcsielias78@gmail.com>

  This file is part of the 'TheRealOne78's error pages' project

  'TheRealOne78's error pages' is free software: you can redistribute it and/or
  modify it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or (at your
  option) any later version.

  'TheRealOne78's error pages' is distributed in the hope that it will be
  useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
  Public License for more details.

  You should have received a copy of the GNU General Public License along with
  'TheRealOne78's error pages'. If not, see <http://www.gnu.org/licenses/>.
-->

<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>404 - Not Found</title>
...
}

Configuring the pages

Because these are plain HTML files and not files with variables, you have to edit each file with the propper URI for the resources paths. This also includes a JavaScript file.

What path should I put?

Depending on how you placed the error pages in the web root, that path will always be the same as the requested one.

Let's take 'example.com' as an example domain.

If you placed the error pages project directory in '/path/to/webroot/err_doc/', then the web path should be 'example.com/err_doc'.

If you configured your error pages project directory to be treated sepparately, you'd have to take that into account, instead of the web root directory. So if 'example.com/' is configured to have the location '/var/www/', but the error pages project directory is in '/usr/share/errors/', you'd have to take into account that in order to not get confused.

Finally, the default state of the error documents is that all paths starts with "this directory". That's erronous because if the client accessed 'example.com/foo/bar.html', it would count the resources files as 'example.com/foo/bar.html/path/to/resource', which is incorrect.

1. Open all files from '/documents/' and replace all './' with the path that will be considered when loading the resources. You might want to consider looking at "Use Vim editor to edit the error documents" instead.

# Example
Find all './', replace with '/errors/'

2. Edit 'script/404.js' and replace the default value from the 'err_res_url' variable with the path that will be considered when loading the resources.

# 404.js - Example
#const err_res_url = "../";
const err_res_url = "/errors/";

Use Vim editor to edit the error documents

Editing all the files is a really tedious task. The vim commands below will help you finish the task faster by using macros. Note that vim or nvim needs to be installed in your system, and this will only work in POSIX compliant shells.

1. Open up a terminal and run the following in your shell:

cd '/path/to/error_pages/documents'
vim *.htm ../index.html

2. Make sure you are in normal mode. Otherwise hit esc (Escape).
3. Type qq (double 'q')
4. Type :%s[\./[<path_that_will_be_considered_when_loading_the_resources>[g. Escape any backslash ('\') from the path with another backslash, like this: \\
5. Hit <Enter> (<Return>)
6. Type :w and hit <Enter>
7. Type :n and hit <Enter>
8. Hit q once
9. Type 42@q
10. Wait. This might take about 1-5 minutes.
11. After vim finished, type :q and hit <Enter> to quit.