Show a Maintenance Page with Nginx: Step-by-Step Guide for Web + Nginx + Docker

Need to put your website into maintenance mode without disrupting users? This guide walks you through setting up a simple, effective maintenance page with Nginx using Docker. Learn how to display a friendly "under maintenance" message using Nginx, Docker, and a little bit of configuration, ensuring a smooth user experience even during updates.

Why Use a Maintenance Page? Minimizing Downtime Frustration

Let's face it, no one likes seeing a broken website. Showing a maintenance page is crucial during updates, deployments, or unexpected issues. Here's why:

User Experience: A clean, informative page prevents confusion and frustration. Instead of errors, users see a clear message that you're working on improvements.
Professionalism: A well-designed maintenance page demonstrates that you care about your users and are actively managing your service.
Control: You decide what users see during downtime, promoting transparency.

Project Overview: Nginx Maintenance Page with Docker

Here's what we're setting up:

Web Service: Uses a placeholder Next.js app which is built with pnpm.

  **Nginx**: Manages traffic and displays the **maintenance page**.

  **Docker**: Containerizes the web service and Nginx for easy deployment.

1. Setting Up Your Web Service (Next.js Example)

First, create a basic Next.js application. This serves as our example web service for this Nginx maintenance page tutorial.

pnpm create next-app maintenance

No need to modify the website content for this example. The focus is on the maintenance page setup.

2. Configuring Nginx for Maintenance Mode

Create a directory structure to store your maintenance page and Nginx configuration:

mkdir data
mkdir data/nginx
cd data/nginx
touch maintenance.html nginx.conf

Designing Your Maintenance Page (maintenance.html)

This is the page your users will see. Keep it simple and informative.

<!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>

Customize this with your branding and expected return time if available, to help with the user experience on your Nginx maintenance page.

Nginx Configuration (nginx.conf)

This file tells Nginx how to handle traffic and display the maintenance page with Nginx.

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;: Listens on port 3000.
error_page 503 /maintenance.html;: When a 503 error occurs, redirect to maintenance.html.
location = /maintenance.html: Serves the static maintenance page.
root /nginx-data;: Specifies the directory where maintenance.html is located.
internal;: Prevents direct access to the maintenance page with Nginx.
if (-f /nginx-data/maintenance.flag): The key! If a file named maintenance.flag exists, return a 503 error, triggering the maintenance page.
proxy_pass http://frontend:3000;: Proxies requests to your web service (running in the frontend Docker container on port 3000).

3. Dockerizing Everything

Now, let's use Docker to package our web service and Nginx configuration.

Dockerfile (for the Next.js App)

Create a Dockerfile in the root directory of your Next.js project:

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

docker-compose.yml

This file defines the services (Next.js app and Nginx) and their configuration.

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

Explanation:

frontend: Builds the Next.js app (using the Dockerfile).
nginx: Uses the latest Nginx image.
ports: Maps port 30000 on your host to port 3000 inside the Nginx container.
volumes: Mounts the following directories:
- ./data/nginx:/nginx-data: Connects your local data/nginx folder to /nginx-data inside the container, making your maintenance.html and flag accessible to Nginx.
- ./data/nginx/nginx.conf:/etc/nginx/conf.d/default.conf: Copies your custom Nginx configuration into the container.
depends_on: Ensures the Next.js app starts before Nginx.
networks: Creates a custom network for communication between the containers.

4. Running the Application and Testing Maintenance Mode

Start the containers:
```
docker compose up --build
```
Access your app: Open localhost:30000 in your browser. You should see your Next.js application.
Enable Maintenance Mode: Create the maintenance.flag file:
```
touch data/nginx/maintenance.flag
```
Refresh your browser: You should now see your maintenance page instead of the Next.js app.
Disable Maintenance Mode: Remove the maintenance.flag file:
```
rm data/nginx/maintenance.flag
```
Refresh again: Your Next.js app should reappear.

5. Streamlining with Scripts (Optional)

Create two simple shell scripts for easier control:

maintenance-on.sh:

#!/bin/bash
touch data/nginx/maintenance.flag

maintenance-off.sh:

#!/bin/bash
rm data/nginx/maintenance.flag

Remember to make them executable: chmod +x maintenance-on.sh maintenance-off.sh

Automating maintenance mode with GitHub Actions

You can use these scripts or commands together with GitHub Actions to further improve this Nginx maintenance page solution.

Conclusion and Further Enhancements

You've now successfully implemented a maintenance page with Nginx using Docker! This provides a reliable way to inform users during downtime.

Show a Maintenance Page with Nginx: Step-by-Step Guide for Web + Nginx + Docker

Why Use a Maintenance Page? Minimizing Downtime Frustration

Let's face it, no one likes seeing a broken website. Showing a maintenance page is crucial during updates, deployments, or unexpected issues. Here's why:

User Experience: A clean, informative page prevents confusion and frustration. Instead of errors, users see a clear message that you're working on improvements.
Professionalism: A well-designed maintenance page demonstrates that you care about your users and are actively managing your service.
Control: You decide what users see during downtime, promoting transparency.

Project Overview: Nginx Maintenance Page with Docker

Here's what we're setting up:

Web Service: Uses a placeholder Next.js app which is built with pnpm.

  **Nginx**: Manages traffic and displays the **maintenance page**.

  **Docker**: Containerizes the web service and Nginx for easy deployment.

1. Setting Up Your Web Service (Next.js Example)

First, create a basic Next.js application. This serves as our example web service for this Nginx maintenance page tutorial.

pnpm create next-app maintenance

No need to modify the website content for this example. The focus is on the maintenance page setup.

2. Configuring Nginx for Maintenance Mode

Create a directory structure to store your maintenance page and Nginx configuration:

mkdir data
mkdir data/nginx
cd data/nginx
touch maintenance.html nginx.conf

Designing Your Maintenance Page (maintenance.html)

This is the page your users will see. Keep it simple and informative.

<!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>

Customize this with your branding and expected return time if available, to help with the user experience on your Nginx maintenance page.

Nginx Configuration (nginx.conf)

This file tells Nginx how to handle traffic and display the maintenance page with Nginx.

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;: Listens on port 3000.
error_page 503 /maintenance.html;: When a 503 error occurs, redirect to maintenance.html.
location = /maintenance.html: Serves the static maintenance page.
root /nginx-data;: Specifies the directory where maintenance.html is located.
internal;: Prevents direct access to the maintenance page with Nginx.
if (-f /nginx-data/maintenance.flag): The key! If a file named maintenance.flag exists, return a 503 error, triggering the maintenance page.
proxy_pass http://frontend:3000;: Proxies requests to your web service (running in the frontend Docker container on port 3000).

3. Dockerizing Everything

Now, let's use Docker to package our web service and Nginx configuration.

Dockerfile (for the Next.js App)

Create a Dockerfile in the root directory of your Next.js project:

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

docker-compose.yml

This file defines the services (Next.js app and Nginx) and their configuration.

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

Explanation:

frontend: Builds the Next.js app (using the Dockerfile).
nginx: Uses the latest Nginx image.
ports: Maps port 30000 on your host to port 3000 inside the Nginx container.
volumes: Mounts the following directories:
- ./data/nginx:/nginx-data: Connects your local data/nginx folder to /nginx-data inside the container, making your maintenance.html and flag accessible to Nginx.
- ./data/nginx/nginx.conf:/etc/nginx/conf.d/default.conf: Copies your custom Nginx configuration into the container.
depends_on: Ensures the Next.js app starts before Nginx.
networks: Creates a custom network for communication between the containers.

4. Running the Application and Testing Maintenance Mode

Start the containers:
```
docker compose up --build
```
Access your app: Open localhost:30000 in your browser. You should see your Next.js application.
Enable Maintenance Mode: Create the maintenance.flag file:
```
touch data/nginx/maintenance.flag
```
Refresh your browser: You should now see your maintenance page instead of the Next.js app.
Disable Maintenance Mode: Remove the maintenance.flag file:
```
rm data/nginx/maintenance.flag
```
Refresh again: Your Next.js app should reappear.

5. Streamlining with Scripts (Optional)

Create two simple shell scripts for easier control:

maintenance-on.sh:

#!/bin/bash
touch data/nginx/maintenance.flag

maintenance-off.sh:

#!/bin/bash
rm data/nginx/maintenance.flag

Remember to make them executable: chmod +x maintenance-on.sh maintenance-off.sh

Automating maintenance mode with GitHub Actions

You can use these scripts or commands together with GitHub Actions to further improve this Nginx maintenance page solution.

Conclusion and Further Enhancements

You've now successfully implemented a maintenance page with Nginx using Docker! This provides a reliable way to inform users during downtime.

Show a Maintenance Page with Nginx: Step-by-Step Guide for Web + Nginx + Docker

Why Use a Maintenance Page? Minimizing Downtime Frustration

Project Overview: Nginx Maintenance Page with Docker

1. Setting Up Your Web Service (Next.js Example)

2. Configuring Nginx for Maintenance Mode

Designing Your Maintenance Page (maintenance.html)

Nginx Configuration (nginx.conf)

3. Dockerizing Everything

Dockerfile (for the Next.js App)

docker-compose.yml

4. Running the Application and Testing Maintenance Mode

5. Streamlining with Scripts (Optional)

Automating maintenance mode with GitHub Actions

Conclusion and Further Enhancements

Show a Maintenance Page with Nginx: Step-by-Step Guide for Web + Nginx + Docker

Why Use a Maintenance Page? Minimizing Downtime Frustration

Project Overview: Nginx Maintenance Page with Docker

1. Setting Up Your Web Service (Next.js Example)

2. Configuring Nginx for Maintenance Mode

Designing Your Maintenance Page (maintenance.html)

Nginx Configuration (nginx.conf)

3. Dockerizing Everything

Dockerfile (for the Next.js App)

docker-compose.yml

4. Running the Application and Testing Maintenance Mode

5. Streamlining with Scripts (Optional)

Automating maintenance mode with GitHub Actions

Conclusion and Further Enhancements

Related Posts