avisenaalwi/custom-http-error-page repository overview

⁠🧱 Custom HTTP Error Page

A lightweight Express-based custom HTTP error page service designed to be used as a standalone container or behind a reverse proxy (e.g., Nginx, Traefik). It serves clean, user-friendly error pages for standard HTTP error codes (403, 404, 500, 502, 503, 504) — with full support for custom HTML templates.

⁠📖 Table of Contents

• 🚀 Features⁠
• 🐋 Docker Image⁠
• 💡 Usage⁠
• 🧩 Custom Templates⁠
• 🧰 Docker Compose Setup⁠
• 🧾 Environment Variables⁠
• 🧠 Route Behavior⁠
• 🧱 Template Guidelines⁠
• 🧑‍💻 Local Development⁠
• 🧰 Maintenance Tasks⁠
• 📦 Image Reference⁠
• 🧾 License⁠

⁠🚀 Features

• 🧩 Simple and lightweight — powered by Node.js + Express
• 🧠 Smart fallback system — automatically falls back to 5xx.html or a generic EJS template if a file doesn’t exist
• 💅 Mobile-friendly & dark-mode aware design
• 🐳 Docker-ready — just pull and run
• ⚙️ Customizable templates through volume mounting

⁠🐋 Docker Image

Image Name:

avisenaalwi/custom-http-error-page

You can pull it directly from Docker Hub:

docker pull avisenaalwi/custom-http-error-page:latest

⁠💡 Usage

Run the container on port 8080 (or any port you like):

docker run -d \
  -p 8080:80 \
  --name custom-http-error-page \
  avisenaalwi/custom-http-error-page

Now open your browser and visit:

http://localhost:8080/404

or

http://localhost:8080/500

⁠🧩 Customizing Templates

The container looks for HTML files in /app/templates. You can override or add your own template by mounting a volume. Example:

docker run -d \
  -p 8080:80 \
  -v $(pwd)/templates:/app/templates \
  --name custom-http-error-page \
  avisenaalwi/custom-http-error-page

In your local folder ./templates, place any of these files:

File Name Purpose

• 403.html Access forbidden page
• 404.html Page not found
• 500.html Internal server error
• 502.html Bad gateway
• 503.html Service unavailable
• 504.html Gateway timeout
• 5xx.html Generic fallback for any 5xx errors

💡 If the requested file (e.g., 404.html) is missing, the app will automatically fall back to 5xx.html, or render a default EJS-based template.

⁠🧰 Development Setup

If you want to modify or extend the app locally:

⁠1️⃣ Clone the repository

git clone https://github.com/avisenaalwi/custom-http-error-page.git
cd custom-http-error-page

⁠2️⃣ Install dependencies

npm install

⁠3️⃣ Run locally

npm run start

⁠4️⃣ Open in browser

http://localhost:8080/404

⁠🧱 Docker Compose (optional)

Example docker-compose.yml:

version: '3.8'

services:
  custom-http-error-page:
    image: avisenaalwi/custom-http-error-page:latest
    container_name: custom-http-error-page
    ports:
      - "8080:80"
    volumes:
      - ./templates:/app/templates
    environment:
      - NODE_ENV=production

Then run:

docker compose up -d

⁠🧾 Environment Variables

Variable Default Description PORT 8080 Port used by Express inside the container NODE_ENV production Node environment mode

⁠🧠 Route Behavior

Route Example Description

• /403 Returns 403.html if found
• /404 Returns 404.html if found
• /500 Returns 500.html if found
• /502 Returns 502.html if found
• /503 Returns 503.html if found
• /504 Returns 504.html if found
• /999 Returns fallback 5xx.html
• /abc Returns 404.html (invalid code)

⁠🧑‍🎨 Template Tips

Each HTML file can be fully customized with your own design and assets. For best UX, include the following meta tags for responsiveness and dark-mode support:

<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="color-scheme" content="light dark">

🧰 License

Licensed under the Apache 2.0 License. © 2025 Avisena Alwi

❤️ Example Screenshot (optional)

You can include screenshots here showing 404/500 pages once ready.

🛠 Future Plans

🌓 Built-in theme switcher (light/dark)

🌍 Multi-language template support

🔧 Dynamic error customization via environment variables

Made with ❤️ by Avisena Alwi