Caddy | webinstall.dev

To update or switch versions, run webi caddy@stable (or @v2.7, @beta, etc).

Files

These are the files / directories that are created and/or modified with this install:

~/.config/envman/PATH.env
~/.local/bin/caddy

~/.config/caddy/autosave.json
~/.config/caddy/env
~/.local/share/caddy/certificates/
<PROJECT-DIR>/Caddyfile

Cheat Sheet

Caddy makes it easy to use Let's Encrypt to handle HTTPS (TLS/SSL) and to reverse proxy APIs and WebSockets to other apps - such as those written node, Go, python, ruby, and PHP.

We've split what we find most useful into two categories:

Caddy for Developers (Caddyfile)
- Serve Static Files & Directories
- Warning-free HTTPS on localhost
- Redirect (ex: www, https)
- Logging
- Compression
- Reverse Proxy
- Rewrite Paths
- CORS
- Wildcard Domain Example (with DuckDNS)
- TLS on Private DNS (192.168.x.x)
- Variables, Placeholders, Macros, Snippets
- Conditional Logic (if)
- Comprehensive Caddyfile Example
- As a macOS service (launchd & launchctl)
- As a Windows service (starup item)
- As a Linux service (systemd & systemctl)
Caddy for DevOps (JSON Config & API)
- JSON Config Overview
- fmt & lint the Caddyfile
- Caddyfile to JSON Config
- JSON Config Admin
  - Code Editor autocomplete
  - Backup
  - Restore
  - Manage & Update Config
- How to use ENVs
- HTTP Basic Authorization
- Prevent Dev Sites from Hijacking Production SEO
- Wildcard & Private IP Certs
  - libdns DNS Providers
  - lego DNS Providers
- Use HTTP only (no TLS/HTTPS)
- Use Non-Standard Ports
- Permission to Use Ports 80 & 443
- Run with systemd (VM, VPS)
- Run with openrc (Container, Docker)

Caddy for Developers

mkdir -p ~/.config/caddy/
touch ~/.config/caddy/env

caddy run --config ./Caddyfile --envfile ~/.config/caddy/env

run runs in the foreground
start starts a background service (daemon)

Warning: ~/.config/caddy/autosave.json is overwritten each time caddy is run with a Caddyfile!

See also:

Wiki Guides: https://caddy.community/c/wiki/13

How to Serve Files & Directories

Using the convenience file-server command:

caddy file-server --browse --listen :4040

Using Caddyfile:

localhost {
    # ...

    handle /* {
        root * ./public/
        file_server {
            browse
        }
    }
}

browse enables the built-in directory explorer

See also:

How to serve HTTPS on localhost

Caddy can be used to test with https on localhost.

It's fully automatic and works in your local browser without warnings, assuming you accept the prompt to add the temporary root certificate to your OS keychain.

Caddyfile:

localhost {
    handle /api/* {
        reverse_proxy localhost:3000
    }

    handle /* {
        root * ./public/
        file_server {
            # ...
        }
    }
}

caddy run --config ./Caddyfile

See also:

How to Redirect www and HTTPS

HTTPS redirects are automatic.

www redirects can be done like this:

# redirect www to apex domain
www.example.com {
    redir https://example.com{uri} permanent
}

example.com {
    # ...
}

If you have legacy systems that require the reverse, perhaps to deal with legacy cookie policies, you can do that too.

See also:

redir: https://caddyserver.com/docs/caddyfile/directives/redir

How to Log to System Logger

example.com {
    # log to stdout, which is captured by journalctl, etc
    log {
        output stdout
        format console
    }

    # ...
}

See also:

log: https://caddyserver.com/docs/caddyfile/directives/log

How to Enable Compression

example.com {

    # enable streaming compression
    encode gzip zstd

    handle /* {
        file_server {
            root /srv/example.com/public/

            # enable static compression
            precompressed br,gzip
        }
    }

    # ...
}

precompressed will serve index.html.br (or index.html.gz) instead of index.html, when available
- Why not zstd?
  - brotli is best for precompressed (static files)
  - gzip is best for streaming (JSON API).

See also:

How to Reverse Proxy

X-Forwarded-* are set by default:
- X-Forwarded-For (XFR) is the Request IP
- X-Forwarded-Proto (XFP) is set to http for plaintext or https for TLS
- X-Forwarded-Host (XFH) is the original Host header from the client
trusted_proxies can be set to allow header pass thru from another proxy
- private_ranges is a built-in alias for
  192.168.0.0/16 172.16.0.0/12 10.0.0.0/8 127.0.0.1/8 fd00::/8 ::1
X-Accel-Redirect can be set to allow static file passthru serving (also known as X-SendFile or X-LIGHTTPD-send-file)

{
    servers {
        trusted_proxies static private_ranges
    }
}

example.com {
    # ...

    handle /api/* {
        reverse_proxy localhost:3000 {

            @accel header X-Accel-Redirect *
            handle_response @sendfile {
                root * /srv/assets
                rewrite * {http.response.header.X-Accel-Redirect}
                file_server
            }

        }
    }
}

See also:

How to Rewrite Paths

Rather than reverse_proxy, this could just as well be handled by file_server.

handle_path eats the path, whereas handle matches without consuming.

example.com {
    # ...

    # {host}/api/oldpath/* => http://localhost:3000/api/newpath/*
    handle_path /api/oldpath/* {
        rewrite * /api/newpath{path}
        reverse_proxy localhost:3000
    }
}

How to handle CORS Preflight + Request

CORS comes in 3 basic varieties:

Simple Requests
Preflight Requests
Credentialed Requests
(by Origin and/or Authentication)

"Simple Requests"

Simple Requests are those that match:

GET, HEAD, or POST
Accept, Range and traditional Content-Types, which are: \
- application/x-www-form-urlencoded, multipart/form-data, text/plain

Typical use cases include

Static Files
Public Assets
Contact Request Forms

# CORS "Simple Request"
# (for Static Files & Form Posts)
(cors-simple) {
    @match-cors-request-simple {
        not header Origin "{http.request.scheme}://{http.request.host}"
        header Origin "{http.request.header.origin}"
        method GET HEAD POST
    }

    handle @match-cors-request-simple {
        header {
            Access-Control-Allow-Origin "*"
            Access-Control-Expose-Headers *
            defer
        }
    }
}

example.com {
    # ex: POST to unauthenticated forms
    handle /api/public/* {
        import cors-simple
        reverse_proxy localhost:3000
    }

    # ex: GET, HEAD static assets
    handle /* {
        import cors-simple
        file_server {
            /srv/public/
        }
    }
}

API Requests

Typical use cases for this are:

Fully Public APIs
APIs Authenticated by Token or username
- Authentication: Basic <base64(api:token)>
- Authentication: Bearer <token>
POST forms with non-traditional Content-Typesusing
- application/json
- application/graphql+json
- etc

Important Notes:

* wildcards may NOT be used for authenticated API requests
Access-Control-Expose-Headers exposes to JavaScript, not just the browser

# CORS Preflight (OPTIONS) + Request (GET, POST, PATCH, PUT, DELETE)
(cors-api) {
    @match-cors-api-preflight {
        not header Origin "{http.request.scheme}://{http.request.host}"
        header Origin "{http.request.header.origin}"
        method OPTIONS
    }
    handle @match-cors-api-preflight {
        header {
            Access-Control-Allow-Origin "{http.request.header.origin}"
            Access-Control-Allow-Methods "GET, POST, PUT, PATCH, DELETE, OPTIONS"
            Access-Control-Allow-Headers "Origin, Accept, Authorization, Content-Type, X-Requested-With"
            Access-Control-Allow-Credentials "true"
            Access-Control-Max-Age "3600"
            defer
        }
        respond "" 204
    }

    @match-cors-api-request {
        not header Origin "{http.request.scheme}://{http.request.host}"
        header Origin "{http.request.header.origin}"
        not method OPTIONS
    }
    handle @match-cors-api-request {
        header {
            Access-Control-Allow-Origin "{http.request.header.origin}"
            Access-Control-Allow-Credentials "true"
            Access-Control-Max-Age "3600"
            defer
        }
    }
}

api.example.com {
    handle /api/* {
        import cors-api

        reverse_proxy localhost:3000
    }

    # ...
}

Restricted by Origin

Typical use cases for this are:

Allow access to partners or sister domains

Important Notes:

* wildcards can be used for unauthenticated requests

(cors-origin) {
    @match-cors-preflight-{args.0} {
        header Origin "{args.0}"
        method OPTIONS
    }
    handle @match-cors-preflight-{args.0} {
        header {
            Access-Control-Allow-Origin "{args.0}"
            Access-Control-Allow-Methods "GET, POST, PUT, PATCH, DELETE, OPTIONS"
            Access-Control-Allow-Headers *
            Access-Control-Max-Age "3600"
            defer
        }
        respond "" 204
    }

    @match-cors-request-{args.0} {
        header Origin "{args.0}"
        not method OPTIONS
    }
    handle @match-cors-request-{args.0} {
        header {
            Access-Control-Allow-Origin "{http.request.header.origin}"
            Access-Control-Expose-Headers *
            defer
        }
    }
}

partners.example.com {
    import cors-origin https://member.example.com
    import cors-origin https://whatever.com

    file_server {
        root /srv/public/
    }
}

See also:

How to Wildcards & Private DNS

DNS Providers are required for

wildcards (*.example.com)
Private IPs / Private DNS (192.168.x.x)
Running Caddy directly on non-standard ports (3000, 8443)

Example with DuckDNS:

Put the credentials in your dotenv (the name is arbitrary):
caddy.env:
```
MY_DUCKDNS_TOKEN=xxxxxxxx-xxxx-4xxx-8xxx-xxxxxxxxxxxx
```

Add the tls directive in the format of dns <provider> [documented params]:

# a wildcard domain
*.example.duckdns.org {
    tls {
        dns duckdns {env.MY_DUCKDNS_TOKEN}
    }

    # ...
}

# an intranet domain (on a private network, such as 192.168.x.x)
local.example.duckdns.org {
    tls {
        dns duckdns {env.MY_DUCKDNS_TOKEN}
    }

    # ...
}

For more information see How to use libdns providers below in the DevOps section.

See also:

How to use Caddyfile Meta Variables

"Placeholders" and "Shorthand" are the variables that look like:
- {http.request.uri}
- {request.uri}
- {uri}
- {path}
- {host}
- {http.response.header}
- {args[0]}
Environment Variables come in Parse-time and Runtime variety:
- {$DUCKDNS_API_TOKEN}, {$BASIC_AUTH_DIGEST} (parse-time)
- {env.DUCKDNS_API_TOKEN}, {env.BASIC_AUTH_DIGEST} (runtime)

"Named Matchers" can substitute paths in most places:

# match this secret path to find hidden treasures
handle_path /easter-eggs/* {
    root * /srv/my-eggs
    file_server
}

# match this secret header to find hidden treasures
@my-easter-egg {
    header X-Magic-Word "Easter-Egg"
}
handle @my-easter-egg {
    root * /srv/my-eggs
    file_server
}

"Imports" and "Snippets" are the macro templates that look like:

# (template-name)
(my-no-plaintext) {

  # @matcher-name
  @my-plaintext {
      protocol http
  }

  # use of matcher
  redir @my-plaintext https://{host}{uri}
}

example.com {
    # import the snippet
    import my-no-plaintext
}

See also:

Placeholder Hierarchy

Path                                        # Shorthand
├── args[]                                  # in snippets (template functions)
├── env.*
├── http
│   ├── error.+                             # {err.+}
│   ├── matchers
│   │   ├── file.+                          # {file_match.+}
│   │   ├── header_regexp.?
│   │   ├── path_regexp.?
│   │   └── vars_regexp.?
│   ├── regexp.*[]                          # {re.*.1}
│   ├── request
│   │   ├── cookie.*                        # {cookie.*}
│   │   ├── header.*                        # {header.*}
│   │   ├── host
│   │   │   └── labels[]                    # {labels.0} (as rDNS: com.example)
│   │   ├── hostport                        # {hostport}
│   │   ├── method                          # {method}
│   │   ├── port                            # {port}
│   │   ├── remote                          # {remote}
│   │   │   ├── host                        # {remote_host}
│   │   │   └── port                        # {remote_port}
│   │   ├── scheme                          # {scheme}
│   │   ├── tls
│   │   │   ├── cipher_suite                # {tls_cipher}
│   │   │   ├── client
│   │   │   │   ├── certificate_der_base64  # {tls_client_certificate_der_base64}
│   │   │   │   ├── certificate_pem         # {tls_client_certificate_pem}
│   │   │   │   ├── fingerprint             # {tls_client_fingerprint}
│   │   │   │   ├── issuer                  # {tls_client_issuer}
│   │   │   │   ├── serial                  # {tls_client_serial}
│   │   │   │   └── subject                 # {tls_client_subject}
│   │   │   └── version                     # {tls_version}
│   │   ├── uri                             # {uri}
│   │   │   ├── path.+                      # {path.+}
│   │   │   │   ├── dir                     # {dir}
│   │   │   │   └── file.+                  # {file}
│   │   │   │       ├── base                # {file.base}
│   │   │   │       └── ext                 # {file.ext}
│   │   │   └── query.*                     # {query.*}
│   ├── reverse_proxy.+                     # {rp.+}
│   │   └── upstream                        # {upstream}
│   │   │   └── hostport                    # {upstream_hostport}
│   └── vars.*                              # {vars.*}
│       └── client_ip                       # {client_ip}
├── system
│   ├── hostname
│   ├── slash
│   ├── os
│   ├── arch
│   └── wd
└── time
    └── now
        ├── common_log
        ├── http
        ├── unix
        ├── unix_ms
        └── year

[] signifies a list accessible by index, such as labels.0
.+ signifies more pre-defined keys, see docs (linked below) for specifics
.* signifies that the keys are arbitrary per the config or the request
.? signifies that we didn't understand the documentation

See also:

How to Conditional ENVs

There is no if in Caddy, but a matcher with "CEL" does the same thing.

Ex: I only want to enforce HTTP Basic Auth if it's enabled:

localhost {
    @match-enforce-auth `"{$HTTP_BASIC_AUTH_ENABLED}".size() > 0`
    basicauth @match-enforce-auth {
        {$HTTP_BASIC_AUTH_USERNAME} {$HTTP_BASIC_AUTH_PASSWORD_DIGEST}
    }

    # ...
}

You can do slightly more complex expressions on the variety of variables (placeholders), but you'd have to look up the CEL docs.

However, you can only do these expressions in things that have a matcher.

See also:

Putting it All Together

Here's what a fairly basic, but comprehensive and complete Caddyfile looks like:

Caddyfile:

# redirect www to bare domain
www.example.com {
    redir https://example.com{uri} permanent
}

example.com {
    ###########
    # Logging #
    ###########

    # log to stdout, which is captured by journalctl
    log {
        output stdout
        format console
    }

    ###############
    # Compression #
    ###############

    # turn on standard streaming compression
    encode gzip zstd

    ####################
    # Reverse Proxying #
    ####################

    # reverse proxy /api to :3000
    handle /api/* {
        reverse_proxy localhost:3000
    }

    # reverse proxy some "well known" APIs
    handle /.well-known/openid-configuration {
        reverse_proxy localhost:3000
    }
    handle /.well-known/jwks.json {
        reverse_proxy  localhost:3000
    }

    ##################
    # Path Rewriting #
    ##################

    # reverse proxy and rewrite path /api/oldpath/* => /api/newpath/*
    handle_path /api/oldpath/* {
        rewrite * /api/newpath{path}
        reverse_proxy localhost:3000
    }

    ###############
    # File Server #
    ###############

    # serve static files
    handle /* {
        root * /srv/example.com/public/
        file_server {
            precompressed br,gzip
        }
    }
}

How to run Caddy as a macOS Service

To avoid the nitty-gritty details of launchd plist files, you can use serviceman to template out the plist file for you:

Install serviceman
```
webi serviceman
```

Use Serviceman to create a launchd plist file

my_username="$(id -u -n)"

serviceman add --agent --name 'caddy' --workdir ./ -- \
    caddy run --envfile ~/.config/caddy/env --config ./Caddyfile --adapter caddyfile

(this will create ~/Library/LaunchAgents/caddy.plist)

Manage the service with launchctl

launchctl unload -w ~/Library/LaunchAgents/caddy.plist
launchctl load -w ~/Library/LaunchAgents/caddy.plist

This process creates a User-Level service in ~/Library/LaunchAgents. To create a System-Level service in /Library/LaunchDaemons/ instead:

serviceman add --name 'caddy' --workdir ./ --daemon -- \
   caddy run --envfile ~/.config/caddy/env --config ./Caddyfile --adapter caddyfile

How to run Caddy as a Windows Service

Set a Windows Firewall Rule to allow traffic to Caddy.
You can do this with PowerShell by changing YOUR_USER in the script below and running it in cmd.exe as Administrator:

powershell.exe -WindowStyle Hidden -Command $r = Get-NetFirewallRule -DisplayName 'Caddy Web Server' 2> $null; if ($r) {write-host 'found rule';} else {New-NetFirewallRule -DisplayName 'Caddy Web Server' -Direction Inbound $HOME\\.local\\bin\\caddy.exe -Action Allow}

Install serviceman
```
webi serviceman
```

Create a Startup Registry Entry with Serviceman.

serviceman.exe add --name caddy -- \
    caddy run --envfile ~/.config/caddy/env --config ./Caddyfile --adapter caddyfile

You can manage the service directly with Serviceman. For example:
```
serviceman stop caddy
serviceman start caddy
```

This will run caddy as a Startup Item. To run as a true system service see https://caddyserver.com/docs/running#windows-service.

How to run Caddy as a Linux service

This will create a System Service using Caddyfile.
See the notes below to run as a User Service or use the JSON Config.

If you haven't already, create a non-root user. You can use ssh-adduser for this:
```
curl -fsS https://webi.sh/ssh-adduser | sh
```
(this will follow the common industry convention of naming the user app)

Give caddy port-binding privileges. You can use setcap-netbind for this:

webi setcap-netbind
setcap-netbind caddy

(or you can use setcap directly)

my_caddy_path="$( command -v caddy )"
my_caddy_absolute="$( readlink -f "${my_caddy_path}" )"

sudo setcap cap_net_bind_service=+ep "${my_caddy_absolute}"

Install serviceman to template a systemd service unit
```
webi serviceman
```

Use Serviceman to create a systemd config file.

serviceman add --name 'caddy' --daemon -- \
    caddy run --envfile ~/.config/caddy/env --config ./Caddyfile --adapter caddyfile

(this will create /etc/systemd/system/caddy.service)

Manage the service with systemctl and journalctl:

sudo systemctl restart caddy
sudo journalctl -xefu caddy

To create a User Service instead:

use --agent when running serviceman:

serviceman add --agent --name caddy -- \
    caddy run --envfile ~/.config/caddy/env --config ./Caddyfile --adapter caddyfile

(this will create ~/.config/systemd/user/)

user the --user flag to manage services and logs:

systemctl --user enable caddy
systemctl --user restart caddy
journalctl --user -xef -u caddy

To use the JSON Config:

use --resume rather than --config ./Caddyfile

caddy run --resume --envfile ~/.config/caddy/env

Caddy for DevOps

touch ./config.env

caddy run --resume --envfile ./caddy.env
# (resumes from ~/.config/caddy/autosave.json)

--resume overrides --config
the save file is hard coded to ~/.config/caddy/autosave.json
only a single API-enabled instance can resumed at a time
(the workaround is to not use resume, but replace the config file and restart)

To create and load the initial JSON Config, see the Caddyfile to JSON section below.

Where to learn about the JSON config

The best way to learn is to create a Caddyfile and

run caddy adapt ./Caddyfile
or see ~/.config/caddy/autosave.json after any caddy run

Then it's also helpful to read the general overview:

The key things you'll need to learn:

which modules can be nested within others (handle, routes)
which keys are arbitrary (srv0) and which are pre-defined (group, match)
which structures are core to caddy vs which are specific to a module
which structures you can eliminate or deneste (Caddyfile conversion is messy)

How to fmt & lint Caddyfiles

Both caddy fmt and caddy adapt can be used to lint.

caddy fmt --overwrite ./Caddyfile

caddy adapt --config ./Caddyfile

How to convert Caddyfile to JSON

Shown with jq (yq also works well) because it makes the output readable.

caddy adapt --config ./Caddyfile |
    jq > ./caddy.json

You can then load the JSON Config to a live server:

my_config="./caddy.json"

curl -X POST "http://localhost:2019/load" \
    -H "Content-Type: application/json" \
    -d @"${my_config}"

This will immediately overwrite ~/.config/caddy/autosave.json.

Code Editor support for Caddy's JSON API

VS Code and Vim / NeoVim are supported.

See https://github.com/abiosoft/caddy-json-schema.

How to Backup the JSON config

my_date="$( date '+%F_%H.%M.%S' )"

curl "http://localhost:2019/config" -o ./caddy."${my_date}".json

Or copy from ~/.config/caddy/autosave.json

Warning: ~/.config/caddy/autosave.json is overwritten each time caddy is run with a Caddyfile!

How to Restore via the API

This will effectively gracefully restart caddy.

my_config="./caddy.json"

curl -X POST "http://localhost:2019/load" \
    -H "Content-Type: application/json" \
    -d @"${my_config}"

How to Update via the API

It will probably be best (and simplest) to write a new config file programmatically and then upload it whole.

Currently, there is no API to provide idempotent updates ("upsert" or "set"), and many changes that are logically a single unit (such as adding a new site), require updates among a few different structures, such as:

apps.https.servers["srv0"].routes[]
apps.tls.automation.policies[].subjects
apps.tls.certificates.automate[]

However, very, very large config files may benefit from the extra work required to do smaller updates rather than reload the whole config.

Here are some important notes:

PATCH will replace, not modify / merge as you would traditionally expect
PUT will NOT replace, but rather insert into a position
A literal ... in a path, such as POST /config/my-config/... will append
@id may exist as a special key on any object, but must globally unique
GET /id/my_object directly accesses the object with "@id": "my_object"

See also:

How to use ENVs

Caddy's --envfile ./caddy.env parser supports dotenvs in this format:

caddy.env:

FOO="one"
BAR='two'
BAZ=three

They are accessed like {env.FOO} whether in Caddyfile or caddy.json:

example.com {
    file_server * {
        root {env.WWW_ROOT}
    }
}

{
  "apps": {
    "http": {
      "servers": {
        "my-srv0": {
          "listen": [":443"],
          "routes": [
            {
              "match": [{ "host": ["example.com"] }],
              "handle": [
                {
                  "handler": "file_server",
                  "root": "{env.WWW_ROOT}"
                }
              ],
              "terminal": true
            }
          ]
        }
      }
    }
  }
}

Conventionally, the dotenv file should be placed in one of the following locations:

~/.config/caddy/env
<PROJECT-DIR>/caddy.env
<PROJECT-DIR>/.env

It does NOT follow the dotenv spec, in particular:

does not support export prefix
does not interpolate variables in double-quoted " strings

Consider dotenv for better compatibility.

See also:

How to add HTTP Basic Authorization

Digest a password with random salt

cat ./password.txt |
    caddy hash-password

$2a$14$QYYeOtsv0RJixoNZ5frOwuPDiUWl8QBkeMEUBbmnkOHuErlVklzTm

Put the digest into an env file with single quotes (to escape the $s)
caddy.env:

BASIC_AUTH_USERNAME=my-username
BASIC_AUTH_DIGEST='$2a$14$QYYeOtsv0RJixoNZ5frOwuPDiUWl8QBkeMEUBbmnkOHuErlVklzTm'

Reference {env.BASIC_AUTH_DIGEST} in the Caddyfile or caddy.json

example.com {
    handle /* {
        basicauth {
            {env.BASIC_AUTH_USERNAME} {env.BASIC_AUTH_DIGEST}
        }
        root * /home/app/srv/example.com/public/
        file_server
    }
}

How to Prevent Dev Sites from Hijacking Prod

Not caddy specific, but...

By default, dev sites on dev domains will hijack the SEO and damage the reputation of your production domains.

Allowing non-production sites to be indexed may even cause browsers to issue Suspicious Site Blocking on your primary domain.

To prevent search engine and browser confusion

delist your demo, staging, beta, & development from indexing
promote your primary domain as canonical
DO NOT prevent crawling via robots.txt
(counter-intuitive, but pages must be crawled for links to NOT be indexed)
all domains using public TLS certs will be indexed by default
(they are all linked to and crawled from various Certificate Transparency reports)
follow these guidelines even if the dev sites use HTTP Basic Auth

dev.example.com {
    header {
        Link "<https://production.example.com{http.request.orig_uri}>; rel=\"canonical\""
        X-Robots-Tag noindex
    }

    # ...
}

See also:

How to DNS Providers for Wildcard Certs

You will need to use xcaddy to build caddy with DNS module support.

DNS Providers come in two flavors:

libdns instances (newer, fewer providers)
- see https://github.com/caddy-dns
- search dns.providers https://caddyserver.com/docs/modules/
lego singletons (deprecated)
- https://github.com/go-acme/lego#dns-providers
- https://caddyserver.com/docs/modules/dns.providers.lego_deprecated

You can only have ONE lego instance per process, whereas libdns can support multiple providers across multiple domains.

How to use libdns providers

Look for your DNS provider in the official lists:

For this example we'll use DuckDNS (https://github.com/caddy-dns/duckdns).

Put the credentials in your dotenv (the name is arbitrary):
caddy.env:
```
MY_DUCKDNS_TOKEN=xxxxxxxx-xxxx-4xxx-8xxx-xxxxxxxxxxxx
```

Add the tls directive in the format of dns <provider> [documented params]:

example.duckdns.org {
    tls {
        dns duckdns {env.MY_DUCKDNS_TOKEN}
    }

    # ...
}

*.example.duckdns.org {
    tls {
        dns duckdns {env.MY_DUCKDNS_TOKEN}
    }

    # ...
}

When using the JSON config the token key is instead named api_token!

You can see this by running caddy adapt ./Caddyfile on the example above.

How to use lego providers

If you can't find your DNS provider in the libdns list, check to see if it's available in the lego list:

https://github.com/go-acme/lego#dns-providers

For this example we'll use DNSimple (https://go-acme.github.io/lego/dns/dnsimple/).

Put the credentials in your dotenv (which MUST match the docs):
caddy.env:
```
DNSIMPLE_OAUTH_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Add the tls directive in the format of dns lego_deprecated <provider>:

example.com {
    tls {
        dns lego_deprecated dnsimple
    }

    # ...
}

*.example.com {
    tls {
        dns lego_deprecated dnsimple
    }

    # ...
}

How to run caddy on HTTP only (no TLS)

You must use the http:// prefix AND specify a port number:

http://localhost:3080 {
    #...
}

How to run caddy on non-standard ports

http://example.com:3080, https://example.com:3443 {
    #...
}

You cannot get TLS certificates (HTTPS) on non-standard ports unless:

you use a DNS Provider (see the Private IP / Wildcard section)
or you have some sort of special proxy in place

How to allow caddy to bind on 80 & 443

On macOS all programs are allowed to use privileged ports by default.

On Linux there are several ways to add network capabilities for privileged ports:

Use setcap-netbind

webi setcap-netbind
setcap-netbind caddy

Use setcap directly

my_caddy_path="$( command -v caddy )"
my_caddy_absolute="$( readlink -f "${my_caddy_path}" )"

sudo setcap cap_net_bind_service=+ep "${my_caddy_absolute}"

Use setcap through systemd
(see systemd instructions below)
Run as root (such as on single-user containers)
Run as app, but port-forward through the container
(you figure it out)

setcap-netbind must be run each time caddy is updated.

How to run with systemd

systemd is the init system used on most VPS-friendly Linuxes.

Install serviceman to create the systemd config
```
webi serviceman
```

Generate the service file: \

JSON Config

serviceman add --name 'caddy' --daemon -- \
    caddy run --resume --envfile ./caddy.env

Caddyfile

serviceman add --name 'caddy' --daemon -- \
    caddy run --config ./Caddyfile --envfile ./caddy.env

Reload systemd config files, the logging service (it may not be started on a new VPS), and caddy

sudo systemctl daemon-reload
sudo systemctl restart systemd-journald
sudo systemctl restart caddy

If you prefer to create the service file manually, it should look something like this:

/etc/systemd/system/caddy.service:

# Generated for serviceman. Edit as you wish, but leave this line.
# Pre-req
# sudo mkdir -p ~/srv/ /var/log/caddy/
# sudo chown -R app:app /var/log/caddy
# Post-install
# sudo journalctl -xefu caddy

[Unit]
Description=caddy
After=network-online.target
Wants=network-online.target systemd-networkd-wait-online.service

[Service]
# Restart on crash (bad signal), but not on 'clean' failure (error exit code)
# Allow up to 3 restarts within 10 seconds
# (it's unlikely that a user or properly-running script will do this)
Restart=always
StartLimitInterval=10
StartLimitBurst=3

# User and group the process will run as
User=app
Group=app

WorkingDirectory=/home/app/srv/
ExecStart=/home/app/.local/bin/caddy run --resume --envfile /home/app/srv/caddy.env
TimeoutStopSec=5s
LimitNOFILE=1048576
LimitNPROC=512
PrivateTmp=true
ProtectSystem=full

# These directives allow the service to gain root-like networking privileges.
# Note that you may have to add capabilities required by any plugins in use.
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
NoNewPrivileges=true

# Caveat: Some features may need additional capabilities.
# For example an "upload" may need CAP_LEASE
; CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_BIND_SERVICE CAP_LEASE
; AmbientCapabilities=CAP_NET_ADMIN CAP_NET_BIND_SERVICE CAP_LEASE
; NoNewPrivileges=true

[Install]
WantedBy=multi-user.target

See also:

How to run with openrc

openrc is the init system on Alpine and other Docker and container-friendly Linuxes.

/etc/init.d/caddy:

#!/sbin/openrc-run
supervisor=supervise-daemon

name="Caddy web server"
description="Fast, multi-platform web server with automatic HTTPS"
description_checkconfig="Check configuration"
description_reload="Reload configuration without downtime"

# for JSON Config
: ${caddy_opts:="--envfile /root/.config/caddy/env --resume"}

# for Caddyfile
#: ${caddy_opts:="--envfile /root/.config/caddy/env --config /root/srv/caddy/Caddyfile"}

command=/root/bin/caddy
command_args="run $caddy_opts"
command_user=root:root
extra_commands="checkconfig"
extra_started_commands="reload"
output_log=/var/log/caddy.log
error_log=/var/log/caddy.err

depend() {
    need net localmount
    after firewall
}

checkconfig() {
    ebegin "Checking configuration for $name"
    su ${command_user%:*} -s /bin/sh -c "$command validate $caddy_opts"
    eend $?
}

reload() {
    ebegin "Reloading $name"
    su ${command_user%:*} -s /bin/sh -c "$command reload $caddy_opts"
    eend $?
}

stop_pre() {
    if [ "$RC_CMD" = restart ]; then
        checkconfig || return $?
    fi
}

Files

Cheat Sheet

Caddy for Developers

How to Serve Files & Directories

How to serve HTTPS on localhost

How to Redirect www and HTTPS

How to Log to System Logger

How to Enable Compression

How to Reverse Proxy

How to Rewrite Paths

How to handle CORS Preflight + Request

"Simple Requests"

API Requests

Restricted by Origin

How to Wildcards & Private DNS

How to use Caddyfile Meta Variables

Placeholder Hierarchy

How to Conditional ENVs

Putting it All Together

How to run Caddy as a macOS Service

How to run Caddy as a Windows Service

How to run Caddy as a Linux service

Caddy for DevOps

Where to learn about the JSON config

How to fmt & lint Caddyfiles

How to convert Caddyfile to JSON

Code Editor support for Caddy's JSON API

How to Backup the JSON config

How to Restore via the API

How to Update via the API

How to use ENVs

How to add HTTP Basic Authorization

How to Prevent Dev Sites from Hijacking Prod

How to DNS Providers for Wildcard Certs

How to use libdns providers

How to use lego providers

How to run caddy on HTTP only (no TLS)

How to run caddy on non-standard ports

How to allow caddy to bind on 80 & 443

How to run with systemd

How to run with openrc

Contribute