Configuration¶

This page shows where Caddy's configuration lives, how to change it safely, and how to go from the loopback sample to proxying your own application.

Where configuration lives¶

Path	What it is
`/etc/caddy/Caddyfile`	The live configuration, written on first boot. Owned by `root:caddy`, mode 0640.
`/usr/local/share/sushi-caddy/Caddyfile.template`	The template first boot starts from.
`/etc/caddy/pilot.password`	The basic auth password for user `pilot`. `root` only, mode 0600.
`/etc/caddy/local-root.crt`	Public certificate of the instance's local CA, for clients.
`/var/lib/caddy/data`	Caddy's data, including the local CA's private key.
`/var/lib/caddy/origin`	The sample site served on port 8080.

First boot writes the Caddyfile only if one does not exist yet. Your edits are kept across reboots.

The default Caddyfile has three parts:

Global options: the admin API on 127.0.0.1:2019, persist_config off, and auto_https disable_redirects, so Caddy does not add a listener on port 80.
http://127.0.0.1:8080: serves the sample site from /var/lib/caddy/origin.
https://127.0.0.1:8443: tls internal, proxies /api/* to port 8080, protects /private/api/status.json with basic auth, and serves the sample page for everything else.

Apply a change¶

Edit the file:
```
sudo nano /etc/caddy/Caddyfile
```

Validate it as the caddy user, with the same data directories the service uses:

sudo -u caddy env XDG_DATA_HOME=/var/lib/caddy/data \
  XDG_CONFIG_HOME=/var/lib/caddy/config \
  caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile

Reload Caddy without dropping connections:
```
sudo systemctl reload caddy
```

If validation fails, fix the file before you reload.

Proxy your own application¶

To put Caddy in front of an application on the same instance, for example one listening on 127.0.0.1:3000, change the reverse_proxy target in the https://127.0.0.1:8443 block:

https://127.0.0.1:8443 {
    bind 127.0.0.1
    tls internal
    reverse_proxy 127.0.0.1:3000
}

Then validate and reload as above.

Change the basic auth password¶

Caddy stores a bcrypt hash of the password in the Caddyfile, not the password itself. To set a new one:

Create a hash. caddy hash-password prompts for the new password and prints its hash:
```
caddy hash-password
```
Replace the hash after pilot in the basic_auth block of /etc/caddy/Caddyfile.
Validate and reload.

If you keep a copy of the password in /etc/caddy/pilot.password, update it too. Caddy does not read that file. It is only there so you can retrieve the password generated on first boot.

Serve a public name¶

The image does not enable public HTTPS and does not contact any certificate authority. To serve a real domain with Caddy's automatic HTTPS, you make these changes yourself:

Point a DNS record for your domain at the instance.

Add a site block for that name, for example:

example.com {
    reverse_proxy 127.0.0.1:3000
}

Let Caddy bind ports 80 and 443. The shipped caddy.service does not grant the CAP_NET_BIND_SERVICE capability, so add it with a drop-in:
```
sudo systemctl edit caddy
```
```
[Service]
AmbientCapabilities=CAP_NET_BIND_SERVICE
```
Remove auto_https disable_redirects from the global options if you want Caddy to redirect HTTP to HTTPS.
Open TCP 80 and 443 in the security group, and allow outbound HTTPS so Caddy can reach the certificate authority.
Restart Caddy so it picks up the new capability:
```
sudo systemctl restart caddy
```

See Automatic HTTPS in the Caddy documentation for how certificates are obtained and renewed.

Test public HTTPS on a pilot first

Software Sushi has not tested public certificate issuance on this image. Try it on a test domain before you move real traffic to it.

Keep the admin API private¶

The admin API on 127.0.0.1:2019 has no password. Anyone who can connect to it can change the proxy. Keep it on 127.0.0.1 and never open ports 2019, 8080 or 8443 in a security group.