Nginx Maintenance Page: A Step-by-Step Guide with Docker and Examples

Want to keep your users informed during website maintenance? Learn how to display a custom Nginx maintenance page using Docker and a few simple configurations. This tutorial provides a practical, easy-to-implement solution for planned outages or emergency updates, ensuring a smoother user experience.

Why Show an Nginx Maintenance Page?

Unexpected errors or website downtime can frustrate users. Displaying a friendly website maintenance page offers several key benefits:

Improved User Experience: Instead of a generic error message, users see a clear message explaining the situation.
Reduced Bounce Rate: Inform users that the site will be back soon, encouraging them to return later.
Professionalism: A custom page demonstrates that you're aware of the issue and actively working to resolve it.

What You'll Need: Essential Technologies

This tutorial leverages the following technologies:

Web service: In this post, it is made using Nginx and its development server.
Nginx: For managing traffic and displaying the maintenance page.
Docker: For containerizing the application.

Ready to get started? Let's dive into the setup process.

Step 1: Setting Up Sample a Web Service

For this example, we'll create a simple Next.js application.

pnpm create next-app maintenance

No modifications to the default website are needed for this demonstration. Any web service can be used.

Step 2: Configuring Nginx for Maintenance Mode

Create a data folder: In the project root, create a folder named data. Inside, create an nginx folder. This folder will hold the maintenance.html file and the nginx.conf file.
Create a Custom maintenance.html: Create a simple HTML file in the data/nginx folder explaining that the site is undergoing maintenance.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>We will be back soon!</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
    <h1>Sorry!</h1>
    <p>We are updating our web server to provide a better and more convenient service. Please wait a moment. The service
    will be back shortly.</p>
</body>
</html>

Create nginx.conf: This configuration file tells Nginx how to handle requests during maintenance.

server {
    listen 3000;
    error_page 503 /maintenance.html; # where to send 503s
    location = /maintenance.html { # serve the static page
        root /nginx-data;
        internal; # prevent direct linking when not in maintenance
    }
    location / {
        if (-f /nginx-data/maintenance.flag) {
            return 503; # send 503 Service Unavailable
        }
        proxy_pass http://frontend:3000;
    }
}

Explanation:

listen 3000;: Nginx listens on port 3000.
error_page 503 /maintenance.html;: Defines the path to maintenance page if a 503 error occurs.
location = /maintenance.html;: Serves the maintenance.html page. The internal directive prevents users from accessing it directly.
location /;: Handles all other requests. Checks for the existence of /nginx-data/maintenance.flag. If present, returns a 503 error, triggering the maintenance page. Otherwise, it proxies the request to the application server.

Step 3: Dockerizing Your Application with Docker Compose

Create a Dockerfile: This file defines how to build the Docker image for your Next.js application.

FROM node:23-alpine
RUN npm install -g pnpm
WORKDIR /app
COPY . .
RUN pnpm install
CMD ["pnpm", "run", "dev"]

Create docker-compose.yml: This file defines the services, networks, and volumes for your Docker environment.

services:
  frontend:
    build:
      context: .
      dockerfile: Dockerfile
    networks:
      - custom
  nginx:
    image: nginx:latest
    restart: always
    ports:
      - '30000:3000'
    volumes:
      - ./data/nginx:/nginx-data
      - ./data/nginx/nginx.conf:/etc/nginx/conf.d/default.conf
    depends_on:
      - frontend
    networks:
      - custom
networks:
  custom:
    driver: bridge

Key Points:

frontend: Builds the Next.js application image from the Dockerfile.
nginx: Uses the latest Nginx image, maps port 30000 to the container's port 3000, and mounts the nginx.conf and data/nginx directory.
The volumes section is important. It mounts the local ./data/nginx directory to /nginx-data inside the container, making the maintenance.html and nginx.conf accessible. It also mounts the nginx.conf file to Nginx's configuration directory.
depends_on: Ensures that the frontend service starts before Nginx.

Step 4: Toggle Maintenance Mode

Create two shell scripts to easily toggle maintenance mode on and off.

maintenance-on:

touch ./data/nginx/maintenance.flag

maintenance-off:

rm ./data/nginx/maintenance.flag

Make sure these scripts are executable: chmod +x maintenance-on maintenance-off.

Step 5: Running the Application and Testing

Start the Docker Compose environment:
```
docker compose up --build
```
Access the application: Open your browser and visit localhost:30000. You should see your Next.js application running.
Enable Maintenance Mode: Run ./maintenance-on. Refresh your browser. You should now see the custom Nginx maintenance page.
Disable Maintenance Mode: Run ./maintenance-off. Refresh your browser again. The Next.js application should be visible again.

Conclusion: Mastering Nginx Maintenance Pages

This tutorial demonstrated a simple yet effective way to implement an Nginx maintenance page using Docker and Docker Compose. You can customize the maintenance.html page with your branding and update it as needed. This example can be extended to automatically turn the maintenance mode on and off during deployments using CI/CD pipelines. Maintaining a website under construction page offers a much better user experience than showing them when your application is misbehaving.