Caddy start vs. caddy run?

No doubt there’s something relatively straightforward I’m missing, but the docs on these two commands have me a little confused. caddy run is described as:

Runs Caddy and blocks indefinitely; i.e. “daemon” mode.

caddy start is described with:

Same as caddy run , but in the background. This command only blocks until the background process is running successfully (or fails to run), then returns.
Use of this command is discouraged with system services

This seems backward to me. “Blocks until the background process is running successfully, then returns” sounds like exactly the desired behavior for a daemon, while “blocks indefinitely” seems like pretty much the opposite of the desired behavior. No doubt I’m missing something basic–what is it?

The context in which I’m asking is, of course, my Nextcloud script for FreeNAS. The proposed rc script in the port, which I’m using with slight modifications, uses caddy start, which appears to preclude --envfile (which itself seems like a curious restriction). The complete command from that script is:

start_cmd="${command} start ${caddy_flags} ${caddy_extra_flags} --pidfile ${pidfile} >> ${caddy_logfile} 2>&1"

Where ${command} is /usr/local/bin/caddy, ${caddy_flags} sets the config adapter and Caddyfile location, and ${caddy_extra_flags} is available for, well, extra flags (though there don’t seem to be any other flags that could be used other than --watch). If I change “start” to “run”, predictably, it hangs and prevents the remaining services from starting.

caddy run is basically “run until I hit Ctrl+C” (or until SIGINT is received) kind of mode, and caddy start is a “run in the background, unmanaged” mode.

Caddy v2 uses a config API that listens on localhost:2019 by default (can be disabled, but it’s recommended not to for a few reasons). When using caddy start, Caddy will run a Caddy process unattached and any command like caddy stop or caddy reload will use the config API to send signals to the running Caddy instance (and if the config API is disabled, then these won’t work, i.e. one of the aforementioned reasons). This works cross-platform, including Windows.

Using caddy run is essentially the same except the Caddy process stays attached to your terminal or whatever process manager you’re using.

Our systemd config uses caddy run.

Does that make sense?

Regarding the --envfile thing, I don’t think it was really considered for the caddy start usecase – I’m not sure if that can even work unless the config API also provides an API for pushing env vars? I’m not sure :thinking:

1 Like

Kind of. I guess the idea is that the caddy run process would be “owned” by something other than the terminal, so it can continue to run while not blocking further terminal activity. This could even be something like screen. The FreeBSD Caddy v1 rc script used /usr/sbin/daemon, which may be able to handle this.

The concern is for DNS validation. Right now there aren’t many native Caddy v2 plugins; the others are all in lego_deprecated. But to use those requires passing the credentials to Caddy by way of environment variables. Which caddy start doesn’t support.

Looks like it may be time to bang on the rc script a bit.

That shouldn’t be the case. It should simply inherit the same environment from the parent process.