Caddy: Manual Maintenance Mode

 Posted on 2024-07-13  (Last modified on 2025-06-04)

Coming from NGINX and others the concept of a maintenance mode that can be manually enabled is something I have used many times before.

With Caddy it is equally as easy, just using a less obvious syntax.

It always follows this general pattern:

  • Check if a maintenance.on file exists at a specified location
  • If it does, deliver the maintenance page
  • Otherwise, do the normal thing you do

Doing maintenance pages the way I describe in this post means your webserver is checking a file on disk for every request.

In small deployments this is likely not adding any overhead you need to be concerned with, but keep it in mind.

nginx

To refresh your memory, this patterns looks like this in nginx.

worker_processes  1;
worker_rlimit_nofile 8192;

events {
  worker_connections  4096;
}

http {
  include    /etc/nginx/mime.types;
  index    index.html index.htm index.php;

  server {
    location / {
      set $maintenance 0;
      if (-f /app/maintenance.on) {
        set $maintenance 1;
      }
      if ($maintenance = 1) {
        return 503 "We are performing a maintenance, come back later";
      }

      proxy_pass http://httpbin.org;
    }
  }
}

echo "Normal Operations"
curl http://127.0.0.1/headers

mkdir /app/ && touch /app/maintenance.on

echo "Maintenance Mode"
curl http://127.0.0.1/headers

Caddyfile

With Caddy it works exactly the same, just using a different vocabulary.

:80 {
	@maintenanceModeActive file /app/maintenance.on {
        root /
    }
	handle @maintenanceModeActive {
		respond "We are performing a maintenance, come back later" 503
	}

	reverse_proxy httpbin.org
}

echo "Normal Operations"
curl http://127.0.0.1/headers

mkdir /app/ && touch /app/maintenance.on

echo "Maintenance Mode"
curl http://127.0.0.1/headers
caddy  sysadmin 

See also