HTML Host Template

A minimal, secure Docker + Nginx setup for hosting static websites. Perfect for local development, documentation sites, or quick demos.

Features

• Secure defaults (read-only volumes, localhost binding)
• Nginx Alpine for small image size
• Easy customization via environment variables
• Includes 404 page and CSS scaffolding
• Security headers (X-Content-Type-Options, X-Frame-Options, etc.)
• Gzip compression enabled
• Log rotation and resource limits

Project Structure

html-host-template/
├── .env.example            # Example environment variables
├── .dockerignore           # Files excluded from Docker context
├── docker-compose.yaml     # Docker Compose service
├── nginx/
│   └── default.conf        # Nginx configuration with security headers
└── html/
    ├── index.html
    ├── 404.html
    └── css/
        └── style.css

Prerequisites

• Docker Engine 20.10+
• Docker Compose V2

Getting Started

1. Clone the repository

   git clone <repository-url>
   cd html-host-template
   

2. Configure environment (optional)

   cp .env.example .env
   # Edit .env to configure port, bind address, image, restart policy, and logging
   

3. Start the server

   docker compose up -d
   

4. Visit http://localhost:50002

Customization

Changing the Port

Edit .env and set HOST_PORT=8080 (or any free port). Restart with:

docker compose restart

Adding Your Own Files

Replace everything inside the html/ directory with your static site (HTML, CSS, JS, images). Changes are reflected immediately without restarting the container.

Modifying Nginx Settings

Edit nginx/default.conf, then restart the web service:

docker compose restart web

Exposing to the Network

By default the server binds to 127.0.0.1 (localhost only). To allow external access, set BIND_ADDRESS in your .env file:

BIND_ADDRESS=0.0.0.0

Then restart:

docker compose restart

Warning: For production, place behind a reverse proxy with HTTPS (e.g., Traefik, Caddy, or Nginx with SSL).

Configuration Reference

All options are set in .env (copy from .env.example). Every variable has a built-in default so the file is optional.

Variable	Default	Description
HOST_PORT	50002	Host port mapped to container port 80
BIND_ADDRESS	127.0.0.1	Host address to bind; 0.0.0.0 for public access
CONTAINER_NAME	custom_html_web	Name assigned to the Docker container
NGINX_IMAGE	nginx:alpine	Nginx image tag; pin for reproducible builds
RESTART_POLICY	unless-stopped	Docker restart policy (no, always, on-failure, unless-stopped)
LOG_MAX_SIZE	10m	Max size per log file before rotation
LOG_MAX_FILES	3	Number of rotated log files to retain

Security

• Volumes are mounted :ro (read-only) to prevent container tampering.
• Server listens only on localhost by default.
• Security headers (X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, Referrer-Policy) are enabled.
• For production, always use a reverse proxy with TLS.

Troubleshooting

• Port already in use: Change HOST_PORT in .env.
• Permission denied on logs: Docker manages logs; use docker compose logs web.
• Changes not reflecting: Ensure you saved files and the volume mount path is correct. Restart the container if needed.

Stopping the Server

docker compose down

License

This project is dedicated to the public domain under the CC0 1.0 Universal License.