Home Assistant Add-on: Caddy 2

Home Assistant Add-on: Caddy 2

Caddy 2 is a powerful, enterprise-ready, open source web server with automatic HTTPS


Caddy simplifies your infrastructure. It takes care of TLS certificate renewals,
OCSP stapling, static file serving, reverse proxying, Kubernetes ingress,
and more.



  1. Add the following repository to your instance:
  2. Search for the “Caddy 2” add-on in the add-on store and install it
  3. (Optional) Create a Caddyfile under /share/caddy
  4. Start the add-on

There is currently no other configuration except the Caddyfile itself.

This add-on is my very first one. I made it running with a lot of trial and error. In case you ran into any issues, let’s try to fix it together (github/suggestions/etc) rather than expecting me solving all issues.

Hopy you all can enjoy Caddy 2.

Credits to @korylprince, who created a great Caddy (1) add-on which has now been replaced in my setup.


DNS challenge?

Hi @DavidFW1960,
I assume you would like to know if Caddy 2 (or more specific, this addon) supports the DNS challenge, correct?

Caddy 2 itself supports DNS challenge, see also here.
The DNS specific settings can be configured here.

Now comes the tricky part.
In order to use the DNS challenge with a specified provider, one needs a dedicated plugin, which must be plugged in from the caddy-dns repositories. Check here.
Creating a version including a plugin is currently a rather manual process, as described here.

With Caddy (1) it was much easier, as there was this download page, where you could easily add in your plugins. As far as I read in the Caddy forum, a similar download possibility is planned but not available yet.

Now coming back to the addon. The addon doesn’t support custom binary builds yet. I have it ready locally, but didn’t see an urgend push need yet. Would add it via the next update.
Or let me know if you need this function urgently, then I will push it through.

Hope my explanation helps further.
Thanks for your interest.

I think all the adding are rolled into the one plugin for caddy2 at least that’s how i read the docs.

migrating to caddy2 is still on my list :frowning: I know it has nothing to do with your addon but are v1 caddyfiles compatible to 2?

No they are not. Completely different

Hi @phixion,
as mentioned before, the files are different. But no worries, the changes are well documented, for example here.
All in all, I think Caddy 2 is easier to configure, coming with some nice features. So don’t wait too long with your transition :wink:

@berichta Thanks! Working very nicely :slight_smile:

1 Like

Thanks simply process to upgrade. Here is a working v2 Caddyfile

https://<external.domain.here> {

    tls /ssl/fullchain.pem /ssl/privkey.pem {
		alpn http1.1

    header {
    Strict-Transport-Security "max-age=31536000; includeSubdomains"
    X-XSS-Protection "1; mode=block"
    X-Content-Type-Options "nosniff"
    X-Frame-Options "SAMEORIGIN"
    Referrer-Policy "same-origin"
	reverse_proxy <internal.ip.here>:8123

    log {
	output stdout

1 Like

You’re using the alpn challenge? Does that require port forwarding? I use the DNS challenge which doesn’t but have not played with caddy2 yet. Thanks for the example caddyfile.

I actually don’t use that challenge. It was part of my old config, although I do forward port 443. I use another plugin letsdnsocloud for my certificate and dynamic IP management which uses the DNS challenge and cloudflare.

So I screwed around, held my mouth right and compiled caddy with all the dns addons in depreciated.
Pretty sure I know what to do with the caddyfile.

So to use the DNS challenge, I normally do this in the addon settings:

  - '-agree'
  - '-email'
  - [email protected]
  - '!secret name_user'
  - '!secret name_key'

Where I specify the username and api key for namecheap.

Is this how I would do that in this addon? or do I use an environment.txt file in the /caddy/share folder?

Also think I need this in the caddyfile

tls {
    dns namecheap {env.??????}

I suspect the env is unnecessary if I set the namecheap name and api in the addon config? OR if I use the file what would I put in there?
My secrets look like this:

name_user: NAMECHEAP_API_USER=xxxx
name_key: NAMECHEAP_API_KEY=xxxx

so the

dns namecheap {env.name_user, env.name_key}

with the keys in a file… would that be the correct configuration?

This is just utterly opaque in all the docs and I have spent days screwing with this but I suspect I’m close now.

Hi @DavidFW1960,
The addon currently has no support for environment variables. It hasn’t been added, because I misread the instructions for the legacy-DNS providers such that I thought you can configure everything in the Caddyfile. Also because I don’t make use of them.

Anyway, will have a look at the add-on later. Should be a quick update.

It may be that I can put them in the Caddyfile… I have to specify them somewhere. Thanks for looking into it.

ok so I see you addes env?

log_level: info
  - '--watch'
log_level: info

Invalid yaml - won’t save and I can’t start the addon.

My caddyfile is:

domain.com:port {
    tls {
	    dns lego_deprecated namecheap
    header / {
    Strict-Transport-Security "max-age=31536000; includeSubdomains"
    X-XSS-Protection "1; mode=block"
    X-Content-Type-Options "nosniff"
    X-Frame-Options "SAMEORIGIN"
    Referrer-Policy "same-origin"
    reverse_proxy / localhost:8123 {
        header_upstream Authorization {>Authorization}

Will this work once I can save the addon config and start the addon?

Incidentally, even this right out or your docs won’t save

  - '--watch'
env_vars: []
log_level: info

Hi @DavidFW1960,
Your config looks wrong. Following your explanation, the config should be:

  email: [email protected]
  domain: yourdomain.com
  destination: localhost
  port: 8123
  - '--watch'
    value: xxxx
    value: xxx
log_level: info

Made the env_vars config clearer in the documentation as well. Thanks for the feedback.

As per the above I am using a caddyfile - I even posted it above.
I renamed caddy binary to caddy.bin I assume that is correct?
I will try this tomorrow.

(Also I originally had the email address in the caddyfile as well - forgot that when I redid it. First time for some reason it didn’t save)

I also have multiple sub domains I didn’t post so I need to use a caddyfile

Hi @DavidFW1960,
The top part of the config (“non_caddyfile_config”) needs to be in place, independent of an existing Caddyfile or not. As soon as the addon finds a Caddyfile, these settings will be ignored.
Following my example above, you can leave those settings with the default.

For the custom binary, please don’t rename it to caddy.bin. As stated in the docu, the name should be caddy. This is different to other Caddy (v1) addons.

OK!! I must have missed that in the doc. Easily fixed anyway. Thanks.

I’ll fire it up tomorrow on my dev instance and see what happens… then I can roll it into my production system. Thanks for your help.

Oh… can I use secrets for the Namecheap creeds?