Using Teleport behind Caddy as a reverse proxy

[webvictim]

Edit (December 2024): Teleport has supported tunnelling its TLS multiplexing over websockets since the release of Teleport 15.1, so this guide has been updated with that in mind to remove the requirement to use separate ports.

---

A question that comes up often is how to deploy Teleport with a reverse proxy (like Caddy) in front of it, so that people deploying in homelabs can still expose other public services other than Teleport on the same home IP.

Here's an example of how I did this with Caddy.

Notes

• example.com is my domain
• Caddy is listening externally on port 443 (see "Port Forwarding" below)
• teleport.example.com is the subdomain that Caddy will redirect to the Raspberry Pi I have running Teleport (artemis), where Teleport is listening on port 3080.
• The wildcard *.teleport.example.com is also configured, so I can use applications on subdomains of Teleport using Teleport application access.
• I have DNS A records configured for teleport.example.com and *.teleport.example.com which point to the public IP address of my router.
• Caddy automatically gets and serves TLS certificates from Let's Encrypt for teleport.example.com and *.teleport.example.com
  • My Teleport cluster also has certs from certbot configured under https_keypairs, but this is not a hard requirement when using a reverse proxy.
    • You can remove the tls_insecure_skip_verify from your Caddy config and replace it with tls_server_name teleport.example.com if you also have this set up.

External port forwarding

• 443/tcp is forwarded to port 443 on the Caddy host

Caddy configuration

Caddy's configuration goes into a file called Caddyfile. It also has a Caddyfile.d directory where you can drop configurations for individual sites, rather than using a monolithic config file.

/etc/caddy/Caddyfile.d/teleport.caddyfile:

teleport.example.com, *.teleport.example.com {
    tls {
        dns cloudflare {env.CLOUDFLARE_AUTH_TOKEN}
    }
    reverse_proxy https://artemis:3080 {
                transport http {
                        tls
                        tls_insecure_skip_verify
                }
        }
}

The dns cloudflare line here means that Caddy will perform DNS-01 challenges using Cloudflare, with a token provided via the CLOUDFLARE_AUTH_TOKEN environment variable. If you don't use Cloudflare you can remove the bracketed section and just leave tls by itself to do challenges using the default mechanism. Wildcard certs will require the use of a DNS-01 challenge, however.

Note that to use Cloudflare DNS challenges, your Caddy setup must have the dns.providers.cloudflare module enabled.

Teleport configuration

Teleport is installed straight onto a Raspberry Pi and uses the config file below. You can use the same host as Caddy if you like - just change the mention of artemis in the caddy config to localhost instead.

/etc/teleport.yaml:

version: v3
teleport:
  log:
    output: stderr
    severity: DEBUG
  data_dir: /var/lib/teleport
auth_service:
  enabled: yes
  cluster_name: teleport.example.com
  authentication:
    type: github
    second_factor: webauthn
    webauthn:
      rp_id: teleport.example.com
ssh_service:
  enabled: yes
  labels:
    type: node
  commands:
  - name: hostname
    command: ['/bin/hostname']
    period: 1h0m0s
  - name: teleport_version
    command: ['/usr/local/bin/teleport', 'version']
    period: 1h0m0s
  - name: arch
    command: ['/bin/uname', '-m']
    period: 1h0m0s
  - name: os
    command: ['/bin/uname', '-s']
    period: 1h0m0s
proxy_service:
  enabled: yes
  web_listen_addr: 0.0.0.0:3080
  # The public address is the public hostname/port that can be used to connect to Teleport from the outside
  # Caddy listens on port 443 and redirects to 3080, where Teleport's web UI is served
  public_addr: teleport.example.com:443
  # (optional) Paths to certs from certbot
  https_keypairs: {}
  # Teleport should trust X-Forwarded-For headers from Caddy, which give the remote IP address.
  trust_x_forwarded_for: true

Config for agents joining remotely

version: v3
teleport:
  proxy_server: teleport.example.com:443

[dyay108]

thanks for this. got my setup going.

[cooling75]

Thanks for this! I'm using traefik (still with http challenge) and was struggling the whole day.

[estradeb]

Some more documentation to help anyone trying this. I had to do this with OVH dns provider

• Ovh module

• build and install the new binary
  I placed my binary in /usr/bin/caddy.custom and pointed the systemd file to point to it (/usr/lib/systemd/system/caddy.service)

Make sure you are using the build with the plugin installed
caddy list-modules | egrep ovh

/usr/lib/systemd/system/caddy.service :

[Service]
Type=notify
User=caddy
Group=caddy
ExecStart=/usr/bin/caddy.custom run --environ --config /etc/caddy/Caddyfile
ExecReload=/usr/bin/caddy.custom reload --config /etc/caddy/Caddyfile --force
TimeoutStopSec=5s
LimitNOFILE=1048576
PrivateTmp=true
ProtectSystem=full
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
Environment='OVH_APPLICATION_KEY=xaxaxaxa'
Environment='OVH_APPLICATION_SECRET=xaxaxaxaxaxaxaxa'
Environment='OVH_CONSUMER_KEY=xaxaxaxaxaxaxaxa'
Environment='OVH_ENDPOINT=ovh-eu'

OVH is also making it pretty annoying to manage application tokens and give it the correct permissions.
This guy pointed out the solution

curl -XPOST -H "X-Ovh-Application: <Application Key>" -H "Content-type: application/json" https://eu.api.ovh.com/1.0/auth/credential -d '{"accessRules":[{"method":"POST","path":"/domain/zone/<Nom De Domaine>/record"},{"method":"POST","path":"/domain/zone/<Nom De Domaine>/refresh"},{"method":"DELETE","path":"/domain/zone/<Nom De Domaine>/record/*"}],"redirection": "https://www.foo.com"}'

[one-juru]

Hey @webvictim, thank you for the wonderful guide!

I tried to follow it; however, I can't seem to add a node to the teleport SSH service. I tried to debug this for an hour, managed to make some progress on my own (for example, by finding the trust_x_forwarded_for: true config option, which I think should be added to this guide), but since a few hours I am hard stuck, and would really appreciate some help.

I have installed teleport via this docker-compose file:

services:
  teleport:
    image: public.ecr.aws/gravitational/teleport-distroless:18
    container_name: teleport
    volumes:
      - ./config:/etc/teleport
      - ./data:/var/lib/teleport
    restart: always
    networks:
      - caddy

networks:
  caddy:
    external: true

Have teleport configured like this

version: v2
teleport:
  nodename: ncx40-docker
  data_dir: /var/lib/teleport
  log:
    output: stderr
    severity: DEBUG
    format:
      output: text

auth_service:
  enabled: true
  listen_addr: 0.0.0.0:3025
  proxy_listener_mode: multiplex
  cluster_name: tp.domain.com
  authentication:
    type: local
    second_factor: on
    webauthn:
      rp_id: tp.domain.com
    connector_name: passwordless

ssh_service:
  enabled: yes

proxy_service:
  enabled: true
  web_listen_addr: 0.0.0.0:3080
  public_addr: tp.domain.com:443
  trust_x_forwarded_for: true
  https_keypairs: []
  acme: {}

app_service:
  enabled: false

... and my Caddyfile looks like this:

tp.domain.com, *.tp.domain.com {
    import hetzner

    reverse_proxy https://teleport:3080 {
                transport http {
                        tls
                        tls_insecure_skip_verify
                        tls_server_name tp.domain.com
                }
        }
}

I've played around with the configs a lot, added several directives to the Caddy configuration, like manually setting header_ups, but the result stays the same. The client does not show up, and the client itself does not even show error logs, and on the server console, I can see the following logs:

teleport  | 2026-01-16T17:44:12.272Z INFO [PROC:1]    Handling incoming inventory ping. pid:7.1 id:6459564173177945266 clock:2026-01-16T17:44:12.272Z service/service.go:1409
teleport  | 2026-01-16T17:44:34.494Z DEBU [SSH:PROXY] Closed connection pid:7.1 remote_addr:188.68.XX.XX:36792 sshutils/server.go:560
teleport  | 2026-01-16T17:44:34.494Z DEBU [SSH:PROXY] Closed connection pid:7.1 remote_addr:188.68.XX.XX:36778 sshutils/server.go:560
teleport  | 2026-01-16T17:44:34.494Z DEBU [PROXY:SER] Agent disconnected cluster:tp.domain.com server_id:7b1d5919-fd7e-4254-a4f2-f63b780a4a79.tp.domain.com addr:188.68.XX.XX:36778 reversetunnel/localsite.go:847
teleport  | 2026-01-16T17:44:34.494Z WARN [DISCOVERY] Unhealthy reverse tunnel connection cluster:tp.domain.com remote_addr:188.68.XX.XX:36778 error:[
teleport  | ERROR REPORT:
teleport  | Original Error: *trace.ConnectionProblemError agent disconnected
teleport  | Stack Trace:
teleport  |     github.com/gravitational/teleport/lib/reversetunnel/localsite.go:848 github.com/gravitational/teleport/lib/reversetunnel.(*localSite).handleHeartbeat
teleport  |     runtime/asm_amd64.s:1700 runtime.goexit
teleport  | User Message: agent disconnected] reversetunnel/conn.go:184
teleport  | 2026-01-16T17:44:34.494Z WARN [PROXY:SER] Closing remote connection to agent cluster:tp.domain.com server_id:7b1d5919-fd7e-4254-a4f2-f63b780a4a79.tp.domain.com addr:188.68.XX.XX:36778 reversetunnel/localsite.go:806
teleport  | 2026-01-16T17:44:34.494Z WARN [PROXY:SER] Failed to close heartbeat channel cluster:tp.domain.com error:[EOF] reversetunnel/localsite.go:792

Do you have any idea or further steps I can take to debug this issue further?

Thank you for your time!

[espadolini]

What version of Caddy are you running? From the logs the connection seems to be established correctly (the SSH handshake seems to go through, we know the server ID of the agent that disconnected) and then drops, so maybe there's some idle timeout or max connection time causing issues.

[webvictim]

It might also be worth turning on logging for Caddy, then sharing what's going on there when the reverse tunnel tries to establish (just in case there are errors):

tp.domain.com, *.tp.domain.com {
    import hetzner

    reverse_proxy https://teleport:3080 {
        transport http {
            tls
            tls_insecure_skip_verify
            tls_server_name tp.domain.com
        }
    }

    log {
        format console
    }
}

[one-juru]

Thank you both for your replies!

I am using a custom build version from this Dockerfile based on 2.10.2, since this is the official-documented way to be able to use DNS wildcard certificates from different providers:

FROM caddy:2.10.2-builder-alpine AS builder

RUN caddy-builder \
    github.com/caddy-dns/cloudflare \
    github.com/caddy-dns/hetzner/v2

FROM caddy:2.10.2-alpine

COPY --from=builder /usr/bin/caddy /usr/bin/caddy

I also enabled debug logging for caddy and tried to reconnect the other node by restarting the teleport service, however there was only little output. You can find it here. I didn't find anything to unusual there though, but maybe it helps.

Let me know if I can do anything else :)

[webvictim]

Hey - thanks for your patience. I'm afraid it's pretty hard for us to figure out exactly what's going on here. It doesn't look like anything is wrong with the configs, but clearly something isn't working for you. The only real difference I can think of between your setup and mine is that I'm not running things in Docker. I wonder if that layer could be causing some kind of connectivity issue.

[one-juru]

@webvictim, @espadolini thank you both for your help.
I had some free time this weekend and tried installing teleport behind traefik and nginx (again with docker, but just to be sure).
Sadly, the symptoms are exactly the same - logs and connection tests.

Do you have any last ideas / were you able to replicate the bug with a Docker installation? If you want, I could still grant you access to a vps with everything running on it.

Otherwise, I would probably give up at this point and go back to a direct install of teleport, even though I figured the docker version would be easier to maintain, for me personally.

Thank you both for the amazing product and your help!