How to use Let's Encrypt staging endpoint with Caddy

Wiki
1

If you’re setting up your server for the first time or testing a new network or domain configuration and you are using Let’s Encrypt (one of Caddy’s default certificate authorities), you should use their staging environment to avoid being rate limited.

This is very easy to do in Caddy. At the top of your Caddyfile, specify the acme_ca global option:

{
    acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
}

If you already have a global options block, just add that line to it; don’t create another global options block.

If you are using JSON, the config looks something like this:

{
	"apps": {
		"tls": {
			"automation": {
				"policies": [
					{
						"issuers": [
							{
								"module": "acme",
								"ca": "https://acme-staging-v02.api.letsencrypt.org/directory"
							}
						]
					}
				]
			}
		}
	}
}

The relevant part is, of course, the automation policy that specifies the acme issuer with a ca value of the Let’s Encrypt staging URL. So if you already have a tls app configured in your JSON, for example, simply add or modify the relevant automation policy.

Make sure to visit Let’s Encrypt’s documentation for current rate limits and URL.

That’s it! Once you’re done testing, be sure to remove this line of config and let Caddy use the production endpoint so it gets trusted certificates.

Caddy falls back to staging automatically if there are errors

Setting the staging endpoint is useful if you’re restarting or reloading Caddy frequently during testing. But if Caddy encounters isolated errors in production, it will gracefully fall back to Let’s Encrypt staging endpoint automatically. It will also fall back to other CAs like ZeroSSL. These measures help you avoid being rate limited by Let’s Encrypt. However, at least as of Caddy 2.6, if you stop or reload Caddy, that error-handling state is lost, and it will try Let’s Encrypt prod again. (We may improve this in a future version.)

So if your logs show ACME errors in production, don’t panic. Caddy backs off and retries with staging (and other CAs) until it can successfully get a cert. This works most of the time because usually, certificate-obtain errors are caused by external factors like DNS, firewalls, and other network or system issues that you can fix without touching your web server – especially if it worked before and you didn’t change your web server at all.

However, if your web server configuration needs to be changed, that requires a config reload or a process restart which (currently, at least) loses the error-handling state, so it will try Let’s Encrypt production again unless you specify staging. That’s why it’s important to specify staging if you’re going to be twiddling your server config until it works.

But once you have it working in production, Caddy does its best to mitigate rate limit problems for you if you just leave it running and fix the external problems separately.

5 Likes