How to Create a Custom HTML Page for NGINX in Docker


Creating and serving a custom HTML page using NGINX in a Docker container is a straightforward process that combines web development basics with Docker's flexibility. This article will guide you through creating a simple HTML page and configuring NGINX to serve it from within a Docker container.

Step-by-Step Guide to Creating a Custom HTML Page in NGINX

1. Setting Up Your HTML File

Start by creating an HTML file that you will serve using NGINX. You can use any text editor to create this file.

Example HTML File (index.html):

<!DOCTYPE html>
    <title>Welcome to My NGINX Page</title>
    <h1>Hello, Docker!</h1>
    <p>This is my custom NGINX page running inside a Docker container!</p>

Save this file on your host machine in a directory you will mount to your Docker container.

2. Preparing the Docker Container

Use the official NGINX Docker image and mount your HTML file to replace the default NGINX welcome page.

Example Command to Run NGINX with Custom HTML:

docker run --name my-nginx-html -v $(pwd)/index.html:/usr/share/nginx/html/index.html:ro -p 8080:80 -d nginx
  • --name my-nginx-html assigns a name to your container for easier reference.

  • -v $(pwd)/index.html:/usr/share/nginx/html/index.html:ro mounts your local index.html file to the container's directory where NGINX serves static files. The :ro option mounts the file as read-only.

  • -p 8080:80 maps port 80 of the container to port 8080 on your host.

  • -d runs the container in detached mode.

Expected Output: This command does not produce visible output if executed successfully, but you can check that the container is running using docker ps.

3. Verifying Your Custom Page

To see your custom HTML page, open a web browser and navigate to http://localhost:8080. You should see your HTML content displayed, served by NGINX running in your Docker container.

Best Practices for Serving Custom Pages with NGINX in Docker

  • File Permissions: Ensure the HTML files have appropriate permissions so that the NGINX server inside the container can read them.

  • Use Docker Volumes for Live Updates: For development, mount a volume that points to your HTML file directory so changes can be reflected immediately without needing to rebuild the container.

  • Security: Always validate the content served by NGINX to prevent XSS (Cross-Site Scripting) and other potential security vulnerabilities.

4. Additional Configuration

If you need more complex configurations or multiple pages, consider creating a custom NGINX configuration file and mounting it similarly to the HTML file.

Example of Mounting a Custom NGINX Config:

docker run --name my-custom-nginx -v $(pwd)/default.conf:/etc/nginx/conf.d/default.conf:ro -v $(pwd)/html:/usr/share/nginx/html:ro -p 8080:80 -d nginx


Creating and serving a custom HTML page with NGINX in Docker is an efficient way to manage web content. This setup benefits from Docker's encapsulation and ease of deployment, making it ideal for development, testing, and production environments.

Additional Resources

For more detailed information about NGINX configurations and Docker deployment strategies, visit the official NGINX documentation and the Docker Hub page for NGINX.