# Remote access with Caddy

Put your *arr stack behind Caddy with automatic HTTPS, subdomain or subpath routing, and how to configure Kochab for either shape.

Canonical: https://kochab.io/docs/remote-access-caddy/

Caddy issues and renews its own certificates automatically: point a domain at it and HTTPS mostly
configures itself. This guide covers the Kochab side of a Caddy setup. For installing Caddy and
the full directive reference, see the [Caddy docs](https://caddyserver.com/docs/).

## Minimal Caddyfile

### A subdomain per service

```
sonarr.example.com {
	reverse_proxy localhost:8989
}

radarr.example.com {
	reverse_proxy localhost:7878
}
```

### One hostname, a path per service

```
media.example.com {
	reverse_proxy /sonarr/* localhost:8989
	reverse_proxy /radarr/* localhost:7878
}
```

The path-matched `reverse_proxy` here passes the request through with the path intact - it does
not strip `/sonarr` before forwarding. That matters: Sonarr's own **URL Base** setting has to be
`/sonarr` too, so the two agree on what the path means. `handle_path` is the alternative if you
want Caddy to strip the prefix instead, which then requires leaving Sonarr's own base path empty.

## Configure Kochab

Follow [Add and configure a service](/docs/add-a-service/):

- **Subdomain shape:** enter `https://sonarr.example.com`, no base path.
- **Subpath shape:** set Sonarr's **URL Base** to `/sonarr` in *Settings > General > Host*
  first, then give Kochab the same path - Caddy, Sonarr and Kochab all have to name the same
  prefix. See
  [Reverse proxies and remote access](/docs/remote-access/#pick-the-shape-you-already-run) for
  how to enter it.

Caddy's certificate is real by default, so Kochab validates it with no prompt. If you run Caddy
in its internal-CA mode instead, or test before DNS is pointed at it, see
[Certificate trust](/docs/cert-trust/) for what Kochab does with a self-signed one. If Caddy is
reachable only from outside your home network, see
[Home and away](/docs/remote-access/#home-and-away) for where that hostname goes instead of the
primary address.

## A login gate in front of Caddy

`forward_auth` or `basic_auth` (Caddy 2.8+; the directive was `basicauth` before that) for
Authelia, Authentik, or similar answers Kochab's requests with a login page instead of data, the
same as it would a signed-out browser. Exempt the API path from the gate rather than the whole
service - see
[the bypass fix in the remote-access guide](/docs/remote-access/#the-fix-let-the-api-through),
which also covers the two gates (Cloudflare Access, Pangolin) Kochab can authenticate against
directly instead.

## Verify and troubleshoot

Run **Test & Add**. If it fails, work through
[Why won't Kochab connect to my service?](/docs/troubleshooting/service-wont-connect/) - for the
subpath shape, check for a mismatched or missing URL Base first, and confirm you used
path-matched `reverse_proxy` rather than `handle_path` if Sonarr's own base path is still set.
See
[It works in a browser but Kochab says it's offline](/docs/troubleshooting/works-in-browser-not-kochab/)
if the service loads fine in a browser but Kochab still reports it offline.