# Install an arcade error page

Open `/arcade/errors/` to preview, customize, and download a game, or download the complete `error-pages.zip` collection.
Each page is self-contained: no iframe, external fonts, scripts, or media downloads.
Five existing games are available for every listed code; these are not new games.

## GitHub Pages

Rename `errors/404-breakout.html` (or another 404 game) to `404.html`, put it at the
root of your published site, and deploy normally. For a project hosted below a
subdirectory, change both home links from `/` to your project's homepage path.
GitHub Pages controls which errors can be customized; uploading a 500 file does
not make it an automatic 500 handler.

## nginx / Apache

Copy `errors/` under your website's document root. Merge the corresponding
`.conf.example` into your existing configuration; do not replace your server config.
The examples cover 403, 404, 500, 502, 503 and 504, using Breakout. Change the file
suffix to `racer`, `invaders`, `void-explorer`, or `flappy` to select another game.
For nginx proxy responses, enable `proxy_intercept_errors on` in the relevant
proxy location. For Apache proxied responses, review `ProxyErrorOverride` for your
deployment. Ensure the static error directory bypasses application routing and
can be read without application authentication. Validate configuration before reload.
Only apply HTML error handling to browser routes, not JSON/API endpoints.

## Other codes and platforms

The installer lists every available code. Configure each at the layer that emits
it. Not all hosts support every code or custom response body.

- 401 and 407: preserve authentication challenge headers; 407 belongs at a proxy.
- 405 and 426: preserve required Allow / Upgrade headers and protocol behavior.
- 429 and 503: preserve Retry-After when supplied. Do not automatically retry.
- 408: server may close the connection before showing a custom page.
- 499: nginx records that the client disconnected; there is no connected browser
  left to receive this page. Included only as a reference/demo template.
- 511: belongs to the network's authentication gateway, not an ordinary website.
- 520, 521, 522 and 526: configure at Cloudflare or the emitting CDN. An origin-only
  installation cannot replace a CDN-generated page. Follow provider custom-error
  requirements, supported plans, tokens, and size limits.
- Other templates can be used where the server/application supports that status.

## Offline and outages

A 404 is a response from a reachable server, not a loss of network connectivity.
Once a standalone page arrives, its game runs without further network access.
If the visitor has no network on their first visit, no server can send a page.
Offline navigation needs a service worker installed during an earlier successful
visit and a cached fallback. This package does not install a service worker.
Browser DNS errors and browser TLS warnings cannot be replaced by these files.
During an application outage, a working reverse proxy can serve the local file.
If the entire server is down, use an independently available CDN/error layer.

## Verify your installation

1. Open the downloaded HTML locally with networking disabled; start and play it.
2. Visit a missing nested URL, such as `/missing/deep/page`, on your deployed site.
3. Confirm the response status remains 404, not a redirect or a 200 response.
4. Confirm no game assets are requested and the home link reaches your homepage.
5. If your site uses Content Security Policy, authorize the bundled inline script
   and style blocks using hashes or your host's supported policy mechanism. Do not
   weaken your entire site's policy just for this page.
6. Test application-outage pages in staging. Preserve status and security headers.

## Rebuild after changing games

Run `python scripts/build-errors.py` from `apps/arcade`. The generated files live in `public/arcade/`. Deploy `install.html`,
`error-pages.zip`, and `errors/` alongside the arcade landing page.

References:
https://nginx.org/en/docs/http/ngx_http_core_module.html#error_page,
https://httpd.apache.org/docs/2.4/mod/core.html#errordocument,
https://developers.cloudflare.com/rules/custom-errors/,
https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-custom-404-page-for-your-github-pages-site