How to integrate Let's encrypt into the docker compose configuration

[kreutpet]

i am planning to migrate from nginx proxy manager to sentinel and like have a proper integration of certbot into the docker compose setup of sentinel .
what is the best way to integrate wildcard (for homelab subdomains services ) or single domain into the docker compose ?
in my specific configuration most of the service use wildcard

Are you planning to have support of let's encrypt with a deeper integration of sentinel in the future ?

`services:
sentinel:
image: ghcr.io/raskell-io/sentinel:latest
ports:
- "80:8080"
- "443:8443"
- "9090:9090"
volumes:
- ./config:/etc/sentinel:ro
- ./certs:/etc/sentinel/letsencrypt:ro
- sockets:/var/run/sentinel
depends_on:
- auth-agent
- echo-agent
networks:
- sentinel
- backend

auth-agent:
image: ghcr.io/raskell-io/sentinel-auth:latest
platform: linux/amd64 # Currently AMD64 only
environment:
- SOCKET_PATH=/var/run/sentinel/auth.sock
volumes:
- sockets:/var/run/sentinel
networks:
- sentinel

echo-agent:
image: ghcr.io/raskell-io/sentinel-echo:latest
environment:
- SOCKET_PATH=/var/run/sentinel/echo.sock
volumes:
- sockets:/var/run/sentinel
networks:
- sentinel

certbot:
image: certbot/certbot
volumes:
- ./certs:/etc/sentinel/letsencrypt
entrypoint: "/bin/sh -c 'trap exit TERM; while :; do certbot renew; sleep 12h & wait $${!}; done;'" # Renew certificates every 12 hours

volumes:
sockets:
driver: local

networks:
sentinel:
driver: bridge
backend:
driver: bridge
internal: true
`

`listeners {
listener "https" {
address "0.0.0.0:443"
protocol "https"
tls {
cert "/etc/sentinel/letsencrypt/wildcard.crt"
key "/etc/sentinel/letsencrypt/wildcard.key"
}
}
}

routes {
route "nextcloud" {
matches { host "cloud.home.lan" }
upstream "nextcloud"
}

route "openhab" {
    matches { host "oh.home.lan" }
    upstream "openhab"
}

route "grafana" {
    matches { host "grafana.home.lan" }
    upstream "grafana"
}

}

upstreams {
upstream "nextcloud" { target "192.168.1.11:80" }
upstream "openhab" { target "192.168.1.12:8443" }
upstream "grafana" { target "192.168.1.13:3000" }
}
`

cheers peter

[raffaelschneider]

Hi Peter,

Thanks so much for your interest in Sentinel - it's awesome to see someone planning a migration from nginx-proxy-manager! Your timing is actually perfect: built-in ACME/Let's Encrypt support literally just landed yesterday in version 0.3.2 (Release 26.01_6). So you won't need to run a separate certbot container at all!

Before diving in, I want to be upfront: we're still in early development, so things might be a bit bumpy here and there. That said, we'd be thrilled to have you as one of our first real-world adopters! Your feedback would be invaluable in helping us smooth out the experience for everyone who comes after you. Please don't hesitate to report any issues or rough edges you encounter - we're here to help and genuinely want to make this work well for you.

Here's how the new ACME integration works:

1. Simplified Docker Compose (no certbot needed):

services:
  sentinel:
    image: ghcr.io/raskell-io/sentinel:26.01_6  # or :latest
    ports:
      - "80:8080"    # Needed for HTTP-01 challenges
      - "443:8443"
      - "9090:9090"
    volumes:
      - ./config:/etc/sentinel:ro
      - acme-data:/var/lib/sentinel/acme  # Persistent cert storage
      - sockets:/var/run/sentinel
    networks:
      - sentinel
      - backend

volumes:
  sockets:
  acme-data:  # Persists certificates across restarts

2. Updated KDL Configuration:

listeners {
    // HTTP listener for ACME challenges (required for HTTP-01)
    listener "http" {
        address "0.0.0.0:8080"
        protocol "http"
    }

    listener "https" {
        address "0.0.0.0:8443"
        protocol "https"
        tls {
            acme {
                email "your-email@example.com"
                domains "cloud.home.lan" "oh.home.lan" "grafana.home.lan"
                staging false  // Set to true for testing first!
                storage "/var/lib/sentinel/acme"
                renew-before-days 30
            }
        }
    }
}

A few things to keep in mind:

1. Wildcard certificates: Let's Encrypt requires DNS-01 challenges for wildcards (*.home.lan), and we currently only support HTTP-01. You'll need to list each domain explicitly for now. DNS-01 support (Cloudflare, Route53, etc.) is on our roadmap!

2. Public accessibility: For HTTP-01 validation, Let's Encrypt needs to reach your Sentinel on port 80 from the internet. For homelab behind NAT, you'll need port forwarding set up.

3. Test with staging first: Use staging true initially to avoid hitting rate limits while you're getting things configured.

If you run into any snags or have questions along the way, just drop them here or open an issue. I am happy to help you get up and running!

Cheers,
Raffael

[Lord-KalEl]

I'm searching for a rust proxy and of course an ACME resolver.

I think sentinel is one of my favourite, even it has no GUI … but this is not what I wanted to write in this issue.

So, back to the topic:
It would be great to add native support for Hetzner DNS as a provider for DNS-01 challenges. Hetzner is widely used, especially in Europe, and adding direct integration would simplify wildcard certificate automation for many users.

Additionally, a more flexible, modular system would be highly valuable:
👉 A generic UI module where users can manually add any DNS provider by entering:

API endpoint
Authentication method (e.g. API token, OAuth)
Required headers or payload format

This way, even unsupported providers could be configured without code changes. The system could load these dynamically, similar to how acme.sh or lego handle providers.

Benefits:

Full Hetzner DNS automation without workarounds
Future-proof for any DNS provider
No need to self-host acme-dns or modify containers

Reference:

Hetzner DNS API: https://docs.hetzner.com/dns-api/

Thank you for this excellent project! 🙌

[raffaelschneider]

@Lord-KalEl Great news! I just shipped DNS-01 ACME challenge support in v0.4.0 (Release 26.01_8), which directly addresses your request.

What's Included

Native Hetzner DNS provider:

tls {
    acme {
        email "admin@example.com"
        domains "example.com" "*.example.com"
        challenge-type "dns-01"

        dns-provider {
            type "hetzner"
            credentials-file "/etc/sentinel/secrets/hetzner-dns.json"
        }
    }
}

Generic webhook provider for custom DNS integrations (addresses your "future-proof" request):

dns-provider {
    type "webhook"
    url "https://your-dns-api.example.com/v1"
    auth-header "X-API-Key"
    credentials-file "/etc/sentinel/secrets/webhook.json"
}

The webhook provider calls:

• POST /records → Create TXT record
• DELETE /records/{id} → Delete record
• GET /domains/{domain}/supported → Check domain support

This allows integrating any DNS provider without code changes.

Additional Features

• DNS propagation checking with configurable nameservers and timeouts
• Secure credential loading from files (JSON or plain text) or environment variables
• Automatic cleanup of TXT records after validation

Documentation

• Configuration Guide
• CHANGELOG

Thanks for the feature request! I am so happy I already can have people test this out in the wild. Please report how it went, I am happy to help out as fast as I can. :)

[kreutpet]

very cool , please keep on doing the great work.
currently traveling and have limited time but will definitely test
i need to investigate the webhook with cloudflare first
cheers

[kreutpet]

i just recognized that you already have wildcard certificate support.

i do have cloudflare dns api token , how would a sample configuration of webhook look like for this ?

dns-provider {
    type "webhook"
    url "https://dns-api.internal/v1"
    auth-header "X-API-Key"
    credentials-file "/etc/sentinel/secrets/cloudflare.json"
}

{"token": "my_ cloudflare_dns_api_token"}

thanks