Keep Caddy Running

While Caddy can be run directly with its command line interface, there are numerous advantages to using a service manager to keep it running, such as ensuring it starts automatically when the system reboots and to capture stdout/stderr logs.

• Linux Service
  • Unit Files
  • Manual Installation
  • Using the Service
  • Local HTTPS
  • Overrides
    • Environment variables
    • run and reload override
    • Restart on crash
  • SELinux Considerations
• Windows service
  • sc.exe
  • WinSW
• Docker Compose
  • Setup
  • Usage
  • Local HTTPS

Linux Service

The recommended way to run Caddy on Linux distributions with systemd is with our official systemd unit files.

Unit Files

We provide two different systemd unit files that you can choose between, depending on your use case:

• caddy.service if you configure Caddy with a Caddyfile. If you prefer to use a different config adapter or a JSON config file, you may override the ExecStart and ExecReload commands.

• caddy-api.service if you configure Caddy solely through its API. This service uses the --resume option which will start Caddy using the autosave.json which is persisted by default.

They are very similar, but differ in the ExecStart and ExecReload commands to accommodate the workflows.

If you need to switch between the services, you should disable and stop the previous one before enabling and starting the other. For example, to switch from the caddy service to the caddy-api service:

sudo systemctl disable --now caddy
sudo systemctl enable --now caddy-api

Manual Installation

Some installation methods automatically set up Caddy to run as a service. If you chose a method that did not, you may follow these instructions to do so:

Requirements:

• caddy binary that you downloaded or built from source
• systemctl --version 232 or newer
• sudo privileges

Move the caddy binary into your $PATH, for example:

sudo mv caddy /usr/bin/

Test that it worked:

caddy version

Create a group named caddy:

sudo groupadd --system caddy

Create a user named caddy with a writeable home directory:

sudo useradd --system \
    --gid caddy \
    --create-home \
    --home-dir /var/lib/caddy \
    --shell /usr/sbin/nologin \
    --comment "Caddy web server" \
    caddy

If using a config file, be sure it is readable by the caddy user you just created.

Next, choose a systemd unit file based on your use case.

Double-check the ExecStart and ExecReload directives. Make sure the binary's location and command line arguments are correct for your installation! For example: if using a config file, change your --config path if it is different from the defaults.

The usual place to save the service file is: /etc/systemd/system/caddy.service

After saving your service file, you can start the service for the first time with the usual systemctl dance:

sudo systemctl daemon-reload
sudo systemctl enable --now caddy

Verify that it is running:

systemctl status caddy

Now you're ready to use the service!

Using the Service

If using a Caddyfile, you can edit your configuration with nano, vi, or your preferred editor:

sudo nano /etc/caddy/Caddyfile

You can place your static site files in either /var/www/html or /srv. Make sure the caddy user has permission to read the files.

To verify that the service is running:

systemctl status caddy

The status command will also show the location of the currently running service file.

When running with our official service file, Caddy's output will be redirected to journalctl. To read your full logs and to avoid lines being truncated:

journalctl -u caddy --no-pager | less +G

If using a config file, you can gracefully reload Caddy after making any changes:

sudo systemctl reload caddy

You can stop the service with:

sudo systemctl stop caddy

The Caddy process will run as the caddy user, which has its $HOME set to /var/lib/caddy. This means that:

• The default data storage location (for certificates and other state information) will be in /var/lib/caddy/.local/share/caddy.
• The default config storage location (for the auto-saved JSON config, primarily useful for the caddy-api service) will be in /var/lib/caddy/.config/caddy.

Local HTTPS with systemd

When using Caddy for local development with HTTPS, you might use a hostname like localhost or app.localhost. This enables Local HTTPS using Caddy's local CA to issue certificates.

Since Caddy runs as the caddy user when running as a service, it won't have permission to install its root CA certificate to the system trust store. To do this, run sudo caddy trust to perform installation.

If you want other devices to connect to your server when using the internal issuer, you will need to install the root CA certificate on those devices as well. You can find the root CA certificate at /var/lib/caddy/.local/share/caddy/pki/authorities/local/root.crt. Many web browsers now use their own trust store (ignoring the system's trust store), so you may also need to install the certificate manually there as well.

Overrides

The best way to override aspects of the service files is with this command:

sudo systemctl edit caddy

This will open a blank file with your default terminal text editor in which you can override or add directives to the unit definition. This is called a "drop-in" file.

Environment variables

If you need to define environment variables for use in your config, you may do so like this:

[Service]
Environment="CF_API_TOKEN=super-secret-cloudflare-tokenvalue"

Similarly, if you prefer to maintain a separate file to maintain the environment variables (envfile), you may use the EnvironmentFile directive as such:

[Service]
EnvironmentFile=/etc/caddy/.env

Then your /etc/caddy/.env file may look like this (do not use " quotes around the values):

CF_API_TOKEN=super-secret-cloudflare-tokenvalue

run and reload override

If you need to change the config file from the default of the Caddyfile, to instead using a JSON file (note that Exec* directives must be reset with empty strings before setting a new value):

[Service]
ExecStart=
ExecStart=/usr/bin/caddy run --environ --config /etc/caddy/caddy.json
ExecReload=
ExecReload=/usr/bin/caddy reload --config /etc/caddy/caddy.json

Restart on crash

If you'd like caddy to restart itself after 5s if it ever crashes unexpectedly:

[Service]
# Automatically restart caddy if it crashes except if the exit code was 1
RestartPreventExitStatus=1
Restart=on-failure
RestartSec=5s

Then, save the file and exit the text editor, and restart the service for it to take effect:

sudo systemctl restart caddy

SELinux Considerations

On SELinux enabled systems you have two options:

1. Install Caddy using the COPR repo. Your systemd file and caddy binary will already be created and labelled correctly (so you may ignore this section). If you wish to use a custom build of Caddy, you'll need to label the executable as described below.