Nginx Maintenance Page: A Simple Guide with Docker and Next.js

Want a quick way to display a maintenance page with Nginx when your site's down for updates? This guide uses Docker and a simple Next.js app to show you how. It's perfect for minimizing user frustration while you work behind the scenes. We will also implement tips for showing a maintenance page during essential updates or emergency downtimes.

Why Show a Maintenance Page?

User Experience: Letting users know why your site is unavailable prevents confusion and frustration.
Professionalism: A well-designed Nginx web server maintenance page looks much better than a generic error message.
Control: You decide what message users see during downtime.

What You'll Need

Docker
Docker Compose
Basic understanding of Nginx

1. Set Up Your Web Service (Next.js)

We'll use Next.js for a simple example.

pnpm create next-app maintenance

No need to modify the website for this demonstration.

2. Configure Nginx

Create a data folder with an nginx subfolder. Inside, create these two files:

`maintenance.html` (Your Maintenance Page)

<!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 HTML with your branding and message.

`nginx.conf` (Nginx Configuration)

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: Directs 503 errors to your maintenance page. So that you serve dynamic maintenance page using Nginx.
location = /maintenance.html: Serves the static maintenance page.
internal: Prevents direct access to the maintenance page.
if (-f /nginx-data/maintenance.flag): Checks for a file named maintenance.flag. If it exists, Nginx returns a 503 error, triggering the maintenance page.
proxy_pass http://frontend:3000: Proxies requests to your Next.js app.

3. Docker Setup

`Dockerfile` (For Next.js App)

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

This Dockerfile sets up the Next.js environment.

`docker-compose.yml` (Docker Compose 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

Key Points:

frontend: Builds and runs your Next.js app.
nginx: Uses the latest Nginx image.
ports: Maps port 30000 on your host to port 3000 inside the container.
volumes:
- ./data/nginx:/nginx-data: Mounts your local data/nginx folder to /nginx-data inside the container.
- ./data/nginx/nginx.conf:/etc/nginx/conf.d/default.conf: Copies your Nginx configuration file into the container.
depends_on: Ensures the Next.js app starts before Nginx.

4. Run It!

Run docker compose up in your project directory.
Visit localhost:30000 to see your Next.js app.

5. Toggle Maintenance Mode: Create `maintenance.flag`

To trigger the maintenance page, create a file named maintenance.flag inside the data/nginx folder:

touch data/nginx/maintenance.flag

Now, refresh localhost:30000. You should see your maintenance page.

6. Disable Maintenance Mode: Remove `maintenance.flag`

To bring your site back online, remove the maintenance.flag file:

rm data/nginx/maintenance.flag

Refresh localhost:30000, and your Next.js app should be back.

Automate with Scripts (Optional)

Create these scripts for easier maintenance mode toggling:

`maintenance-on`

touch data/nginx/maintenance.flag

`maintenance-off`

rm data/nginx/maintenance.flag

Make them executable:

chmod +x maintenance-on maintenance-off

Now, you can simply run ./maintenance-on or ./maintenance-off to toggle maintenance mode.

Considerations

GitHub Actions: Automate maintenance mode toggling as part of your deployment process.
Customization: Enhance your maintenance page with dynamic content or countdown timers.
Remote Execution: Run the maintenance mode toggling commands from a remote server.

Wrapping Up

This simple setup gives you a solid foundation for displaying a professional Nginx website maintenance page using Docker. Adapt it to your specific needs and deployment workflow.