c9ff56881e | ||
---|---|---|
.. | ||
README.md | ||
caddy-api.service | ||
caddy-service.md | ||
caddy@.service | ||
install | ||
log | ||
persist | ||
start | ||
stop |
README.md
Official service files for systemd
This folder contains the officially-maintained systemd files that should be used as a basis for your own deployments.
⚠️ Always review your service file before using it! Change anything that you need to customize.
Instructions
See our website for installation instructions.
Prerequisites
Running Caddy as a systemd service requires the following:
Group named caddy
:
$ groupadd --system caddy
User named caddy
with a writeable home folder:
$ useradd --system \
--gid caddy \
--create-home \
--home-dir /var/lib/caddy \
--shell /usr/sbin/nologin \
--comment "Caddy web server" \
caddy
Choosing a service file
caddy.service
- Use this one if you configure Caddy with a file (for example, the Caddyfile, or a .json file).caddy-api.service
- Use this one if you configure Caddy solely through its API.
The two files are identical except for the ExecStart and ExecReload commands.
Important
Caddy receives all configuration through its admin API, even when the command line interface (CLI) is used, which simply wraps up the API calls for you.
Most users will use either config files and the CLI mutually exclusively with the API because it is simpler to have only one source of truth. However, you may wish to provide Caddy an initial "bootstrapping" configuration with a config file, and use the API thereafter.
⚠️ If you provide an initial config file with the --config
flag and then update the config using the API, you risk losing your changes if the service is restarted unless you have the --resume
flag in your ExecStart command.
Without the --resume
flag, the --config
flag will overwrite any last-known configuration.
However, it is totally safe and normal to use both the --config
and --resume
options together if you need to use both a config file and the API. Just be aware that if you update your config file and want to apply those changes, stopping and starting the server is the wrong way to do this. Restarting the service is orthogonal to config changes; this is a unique safety feature that guarantees durability and prevents data loss. If the config file has the latest changes, you should use the reload command instead.