# Remote access with Traefik

Route your *arr stack through Traefik with Docker labels, subdomain or subpath routing, and how to configure Kochab for either shape.

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

Traefik discovers containers through Docker labels, so routing lives next to the service
definition in your compose file rather than in a separate site config. Entrypoints and cert
resolvers still come from Traefik's own static config - labels only add routers and services on
top of it. This guide covers the Kochab side of a Traefik setup. For installing Traefik and the
full provider and middleware reference, see the [Traefik docs](https://doc.traefik.io/traefik/).

## Minimal labels

### A subdomain per service

```yaml
services:
  sonarr:
    image: linuxserver/sonarr
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.sonarr.rule=Host(`sonarr.example.com`)"
      - "traefik.http.routers.sonarr.entrypoints=websecure"
      - "traefik.http.routers.sonarr.tls.certresolver=letsencrypt"
      - "traefik.http.services.sonarr.loadbalancer.server.port=8989"
```

### One hostname, a path per service

```yaml
labels:
  - "traefik.http.routers.sonarr.rule=Host(`media.example.com`) && PathPrefix(`/sonarr`)"
  - "traefik.http.routers.sonarr.entrypoints=websecure"
  - "traefik.http.routers.sonarr.tls.certresolver=letsencrypt"
  - "traefik.http.services.sonarr.loadbalancer.server.port=8989"
```

`PathPrefix` alone routes the request through with `/sonarr` still in the path - Traefik does
not strip it unless a `stripprefix` middleware is attached. Leave the prefix in place: Sonarr's
own **URL Base** setting needs to be `/sonarr` too, and a `stripprefix` middleware would put the
two out of agreement.

## 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 - the router rule, 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.

With a working `certresolver`, Traefik's certificate is real and Kochab validates it with no
prompt. Without one, Traefik falls back to its own self-signed default certificate - see
[Certificate trust](/docs/cert-trust/) for what Kochab does with that. If Traefik 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 Traefik

`traefik-forward-auth` or a similar ForwardAuth middleware answers Kochab's requests with the
same login redirect a signed-out browser would get. Exempt the API path with a second router for
that path, without the ForwardAuth middleware attached, sitting next to the gated router for
everything else - 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 first for a `stripprefix` middleware left on by mistake, since it disagrees
with a URL Base the service still expects to see. 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.