Understanding module installation

1. The problem I’m having:

I would like to start using Caddy to reverse proxy internal sites that have no cert or a self signed cert.
I use cloudflair DNS because of the ability to use the API for DNS verification. I’m simply trying to understand how to use the tool, I haven’t installed anything yet.

I came here because “setup is trivial” but I must be more of a noob than I think because I can’t figure this out. Been digging around in forums and documentation for a few hours now and all I’ve done is get myself frustrated.

I think I understand I need to install the cloudflaire module How to use DNS provider modules in Caddy 2 from Download Caddy. The instructions say " 1. Download your custom Caddy build." then nothing… Download it where? How? What do I do with it? Does it need ran, installed, built, referenced in a config, or just dropped in a folder? Instructions make it sound so easy but I have zero clue what to do with this information.

Once installed it looks pretty straight forward to implement I think, assuming I just add the below to my caddy file along with the reverse proxy info.

acme_dns cloudflare

2. Error messages and/or full log output:

Please use the preview pane to ensure it looks nice.

3. Caddy version:


4. How I installed and ran Caddy:

a. System environment:

b. Command:

Please use the preview pane to ensure it looks nice.

c. Service/unit/compose file:

Please use the preview pane to ensure it looks nice.

d. My complete Caddy config:

Please use the preview pane to ensure it looks nice.

5. Links to relevant resources:

1 Like

Welcome Brandon,

I’m not sure I follow – there’s a lot more text in that guide after that step.

The download page that was linked two lines above, and follow the instructions on just the previous line: " Find your DNS provider in the list of modules (dns.providers.*) and select it." – then click Download. Note, however, that at this time the Go command has a bug in it that is preventing many builds from succeeding. I saw an update this morning that looks like they’re close to fixing it though. If you are having trouble with that then I recommend using xcaddy, which helps you build it on your own machine, or you can just build from source which will be very familiar to you if you’re a Go programmer.

The next section is “Enabling the DNS challenge”:

Once you have a custom Caddy binary with your DNS provider module plugged in, you simply have to enable the DNS challenge in your config. Do this one of the following ways:

Is this your first time running a web server? (I don’t mean to be condescending.) It’s OK if it is – you will just need to know how to use your computer. The instructions for running programs is very different for Windows, Mac, and Linux, so we don’t really cover that in our docs, because that’s less about Caddy and more about your OS. I’d recommend looking at your OS documentation if you have questions there.

I experimented with a more comprehensive system install tutorial but I don’t think I will merge it because it’s out of scope for our website and is too tedious to maintain. Still, maybe the writing there will be of help to you if you’re on Linux.

Once you know how to run the program, we recommend everyone follow our Getting Started guide and the Caddyfile concepts page so you know how the config file is structured.

It definitely is a lot simpler than other web servers which require you to set up HTTPS, TLS certificates, and the management of those certificates all separately with various tools.

Caddy, you just download the binary, and run it with your config file. Done. :slight_smile:

It quite literally says

Method 1:

  1. Go to the Caddy download page .
  2. Find your DNS provider in the list of modules (dns.providers.*) and select it.
  3. Download your custom Caddy build.

Nothing else in that section.

The next area says:

Once you have a custom Caddy binary with your DNS provider module plugged in, you simply have to enable the DNS challenge in your config

It doesn’t however define how to “plug in the module”

Right, but again I don’t know how to “plug it in”, do I put it in a folder, build it, reference it in a conf file somewhere?

No, I’ve been in enterprise tech for about 15+ years. Mainly Microsoft, but dabble in linux distros in my free time. I currently have nginx setup using certbot in front of my splunk server as a reverse proxy. But the config feels janky and usually needs a combination of guides to get up and working with cloudflare DNS, but it works and can be setup in about an hour. I’m here looking for more refined simple option to use LetsEncrypt certs, with less config.

I think this may be an instance where I’m overthinking this or there is some key nuance to the way this works that I simply don’t understand yet. Thanks for the detailed response.

Right, that section is called “Getting a DNS provider plugin” – so that’s the last step to getting Caddy with that plugin.

“a custom Caddy binary with your DNS provider module plugged in” is what you just downloaded, so it’s telling you that “you simply have to enable the DNS challenge in your config”.

You already “plugged it in” by this point, and downloaded the compiled binary.

Run ./caddy list-modules to verify. You should see your plugin in the list.

It seems like it :sweat_smile: Sorry, I’m not really sure how to make this any clearer. You download Caddy with the plugin “plugged in”, then you run it with your config file. It’s those two high-level steps, but the precise exact steps of both kind of depends on your OS.

If we can figure out the disconnect here, that will be helpful as I’m currently working on a new website with new docs.

Ok let me walk through my start to stuck process and see if that helps align it. Really not sure why I’m struggling so much here :upside_down_face: I feel like the instructions are skipping over something critical.

  1. So I first SSH into my Ubuntu web server.
  2. I follow the Caddy install process here Install — Caddy Documentation
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy
  1. I go to Download Caddy
    a. I search for cloudflare (in my instance it’s right on top)
    b. I select it
    c. I select my platform (in my case Linux amd64)
    d. I click download and receive a file called “caddy_linux_amd64_custom”
  2. I’m now dead ended. I do not know what to do with the file “caddy_linux_amd64_custom”. I can upload it to my server, but where? Does it go in a folder? Do I put it wherever I want and build it? Do I put it wherever I want and just reference it somehow?

I feel stupid but I’m completely lost on step 4.

1 Like


That’s the binary with your plugin. Run it with your config.

What you downloaded with apt install caddy it just installs a vanilla Caddy binary. Hence the purple notice at the top of the page:

Our official packages come only with the standard modules. If you need third-party plugins, build from source with xcaddy or use our download page.

Installing a package with apt also sets Caddy up as a system service, which is recommended best practice. But if you need a plugin, you have to replace the binary that the service runs with your custom build. That’s the only difference. We wish this weren’t the case, but apt is an incompetent package manager that can’t configure plugins :frowning:

1 Like

What config? /etc/caddy/Caddyfile?

How? Where does the binary exist now?

1 Like

Tried searching for the binary/s that need replaced but i’m struggling to find or know what i’m replacing.

$ sudo find / -name '*caddy*'

That’s the file that the system service is configured to use by default, yeah. But you could change that if needed. See our CLI docs.

Run which caddy to find out.

That’s helpful this returns /usr/bin/caddy

So I would just take my download “caddy_linux_amd64_custom” and overwrite /usr/bin/caddy? Something like (assuming the file is downloaded in my home directory sudo cp ~/caddy_linux_amd64 /usr/bin/caddy? Am I understanding that correctly to install the plugin/binary?


That’s right. But I recommend following these steps to do a package divert which allows the rest of the files packaged in the .deb to still get updated as needed (i.e. the systemd service and such)


Goodness, ok thank you. That pieces a lot of this together.

I think there were several things that weren’t clear to me, maybe it’s the instructions maybe it’s me. This will be my experience, feel free to do with it as you see fit :sunglasses:

  • The first large hurdle for me is the terminology of “plugin”. I understand how this is working now being packaged with the actual caddy binary. However in my head a plugin is always an addon, think browser plugin, I don’t have to overwrite my browser to install an adblocker. Not sure I’ve ran across this ideology before, assume it’s for a reason, I know you mentioned apt packaging, it just kept my mind thinking the wrong direction.

  • Understanding that I needed to overwrite existing binaries or even more in my case build from source when utilizing a plugin is not clear or even really spelled out anywhere. Instructions make it sound like the plugin would need to just be placed in a folder somewhere. In my mind I was thinking like /etc/caddy/plugins/ or something like that. Then referencing it in a config somewhere. But that’s not how it works, (see first bullet).

  • Then locating the currently installed binaries was also a feat, even digging through the documentation under Conventions > File locations didn’t really lead me to where I could locate them. Using which was a good option, my linux noobness didn’t get me there.

Thank you very much for your patience in walking through this with me, I think I can take it from here.


Thanks for explaining, that’s good information to consider.

Yeah, so one of Caddy’s big advantages is that it’s a static binary. A plugin is added at compile-time, so it’s impossible to end up with a broken program: it’s all self-contained! We do realize that is different from most of the world so the new docs I’ve been designing should make this clearer, although there will be more pages related to “getting Caddy” than there currently are, so that’s the downside.

Ok, I’ll try to make that clearer in the new docs.

Ah yeah, that’s something that comes down to just how to use your computer, I guess. It’s different on Linux, Mac, and Windows, and it’s kind of out of the scope of our documentation. On the other hand, I sympathize, since I’m well aware Linux doesn’t have any documentation worth speaking of. :disappointed: We’re trying to not be like Linux…

1 Like

Ha yea don’t be like Linux :slight_smile:

I’m admittedly a Linux noob and I think in Windows. I’ve spent most of my career there so when I get in the Linux world I get lost quickly. Also in enterprise environment’s I just go buy a cert instead of using proxies and LetsEncrypt (for better or worse). Maybe I should do it this way, would save a lot of money. And on Windows I’ve used CertifyTheWeb which makes getting and implementing LetsEncrypt certs very easy. But I digress and will mark this as solved.


Certify The Web and similar ACME clients are great, but only Caddy has it baked into the server: no need for external tooling :100:

1 Like

Finally I understand how plugins work with Caddy … Thank you guys :blush:

1 Like

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.