How to install caddy cloudflare's plugin?

1. Caddy version (caddy version):

last version (2.4.6)

2. How I run Caddy:

i installed it with apt but would like to know both way to do this (apt & docker)

a. System environment:

ubuntu 20.04
docker ce 20.10.11

b. Command:

c. Service/unit/compose file:

d. My complete Caddyfile or JSON config:

3. The problem I’m having:

i don’t know how to add the cloudflare mod to caddy 2 and didn’t success to with apt and docker

4. Error messages and/or full log output:

5. What I already tried:

something that didn’t help me at all

6. Links to relevant resources:

Hi @TheGodGoldfish,

You can add plugins to Caddy directly on the Download page, or you can use xcaddy to build a binary yourself.

The official Docker image also has instructions on its README explaining how to get a custom build into a Docker container (using xcaddy); you’re looking for the “Adding custom Caddy modules” heading.

See: Download Caddy, GitHub - caddyserver/xcaddy: Build Caddy with plugins, and Docker Hub


i already read that the thing is that i don’t know how to do it once i downloaded the plugin, xcaddy doesn’t work properly and give me an exit code also i didn’t know how to write the docker-compose file to make it work

Okay, there’s a whole lot of different problems to try and unravel here.

Just to clarify, you’re not downloading individual plugins, you’re downloading an entire compiled binary with the plugins you selected included. As for what you do with it, you can just replace your existing binary (the one that has no plugins). Drop-in replacement. Reboot service and you should be good to go.

We might be able to help you with that if you explain what’s happening. What are you trying to achieve with it, what specifically did you try (e.g. what exact commands did you use), and what result did you get (e.g. just copy the outputs - we need to know the exact error codes etc.).

This depends wildly on the specifics of your requirements. But if you’re doing stuff pretty normally, your compose file probably just needs to use the Caddy binary as its entry point, with a command that points it to a mounted Caddyfile, a volume to preserve the TLS assets, and port mappings for whatever you intend Caddy to serve on. Docker help is beyond the scope of these forums, but a number of us here do use Docker ourselves, so we might be able to help with your questions along these lines.


ok about the binary that’s what i thought at the beginning but how am i suppose to deploy this modded binary once i downloaded it ?
also what is the right command to download the binary because once i try i get an error, i have seen this error on an other post on this forum.

for xcaddy i used the command on the github page of xcaddy and get an exit code error so i think something might be wrong with it and not with my command.

could you provide me an example of a docker-compose file that integrate a dockerfile to build caddy with the cloudflare plugin ?

thanks helping me out.

You only need to copy it in place of the existing binary (wherever that is).

Easiest way is not to use a command, but to browse to, select the plugins you want, and use the download button link.


If you have some evidence to suggest xcaddy is broken somehow, or the README is incorrect, we would love to see it. Generally we want to make sure the program works exactly as advertised; as soon as you can tell us what went wrong, we can start looking into it.

Here is the example from the official README on the Docker image:

Docker Compose example

If you prefer to use docker-compoose to run your stack, here’s a sample service definition.

version: "3.7"

    image: caddy:<version>
    restart: unless-stopped
      - "80:80"
      - "443:443"
      - $PWD/Caddyfile:/etc/caddy/Caddyfile
      - $PWD/site:/srv
      - caddy_data:/data
      - caddy_config:/config

    external: true

And here is the official Compose reference documentation regarding defining a service to be built from a Dockerfile: Compose file version 3 reference | Docker Documentation


about xcaddy i followed mainly this :


but both gave me exit code 2 or 1 even if i tried with the latest golang-go version and also previous version, by downloading it from source and with apt it didn’t change.

when using this curl command to download the binary it doesn’t download anything and don’t do anything and just get stuck and nothing happen :

sudo curl -o /usr/bin/caddy -L

about the cloudflare version of caddy once downloaded i don’t understand exactly what needs to be done, the only i know about is that i need to create a service because there is no any.
if i got you well i download this binary and just move it in /usr/bin/caddy and create a service ?

for docker i know how to write a docker-compose file but not how to make the dockerfile that will build and integrate the custom image with the cloudflare plugin inside the docker-compose file.

see the section titled “Adding custom Caddy modules” on that page.


if you are not using docker and want to have the system configured to run caddy;

  1. yes download the caddy binary with the plugin(s) you want for the architecture you are on from Download Caddy

  2. you can replace /usr/bin/caddy or define with update-alternatives to link /usr/bin/caddy to your target release wherever you are staging it on the filesystem

  3. instructions on obtaining the proper systemd unit file are here for ubuntu: Keep Caddy Running — Caddy Documentation


ok so i understood for the non-docker caddy version
but for caddy docker i don’t understand how i am suppose to build the image first and then use it in my docker-compose.

thanks to all of you

Here is the text - quoted in full - from, under the “Adding custom Caddy modules” heading, which has been linked to a few times above.

Caddy is extendable through the use of “modules”. See Extending Caddy — Caddy Documentation for full details. You can find a list of available modules on the Caddy website’s download page.

You can use the :builder image as a short-cut to building a new Caddy binary:

FROM caddy:<version>-builder AS builder

RUN xcaddy build \
    --with \

FROM caddy:<version>

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

Note the second FROM instruction - this produces a much smaller image by simply overlaying the newly-built binary on top of the the regular caddy image.

The xcaddy tool is used to build a new Caddy entrypoint, with the provided modules. You can specify just a module name, or a name with a version (separated by @). You can also specify a specific version (can be a version tag or commit hash) of Caddy to build from. Read more about xcaddy usage.

Note that the “standard” Caddy modules ( are always included.

Where are you running into trouble?


i just don’t understand how to start the build of the image with the dockerfile and then what image i have to put in the docker-compose.

i suppose that i will not use caddy:latest as my image i need to use the special one i just builded right ?

That’s right. Since you’re defining a build operation, you don’t specify any image at all - the service will use the container it builds.

You might find Get started with Docker Compose | Docker Documentation useful; it outlines the basic concepts around writing Compose configuration to leverage a Dockerfile.

1 Like

so as a recap i create a Dockerfile like that :

FROM caddy:latest-builder AS builder

RUN xcaddy build --with

FROM caddy:latest

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

and then in my docker-compose file like that :

version: "3.9"
      context: /opt/caddy/
      dockerfile: Dockerfile
    container_name: caddy2-cloudflare
    restart: always
      - 80:80
      - 443:443
      - $PWD/Caddyfile:/etc/caddy/Caddyfile
      - $PWD/site:/srv
      - caddy_data:/data
      - caddy_config:/config

    external: true
    external: true

and it should build the image and use it right ?

:latest-builder doesn’t exist. You can use either :builder, or :2.4.6-builder. Refer to the top of the page on Docker Hub to see the full list of valid tags.

Generally, it’s best to pin to a specific version, so that you explicitly upgrade on your own time. There’s no guarantee that changes in Caddy won’t be breaking – we may make a change to some configuration option (we try to avoid them, but it can happen that we need to do it for important reasons). Using latest is dangerous for that reason.

You can simplify this to just:

    build: /opt/caddy

Basically, it just needs to be a path to the directory that contains your Dockerfile. If your docker-compose.yml is right beside your Dockerfile, you could simplify it even more to just this:

    build: .

You don’t need this line, because the default container name will be the name of the service, i.e. caddy, prefixed with the project name (which by default is the directory in which you’re running your docker-compose commands, if that’s /opt/caddy then the project name will be caddy) and suffixed by a number (in case you were to run multiple replicas – you aren’t though). So your container name would be caddy_caddy_1. Which is fine.

Yep. First time you run docker-compose up -d, it’ll build it. Next time you run it, it’ll already have been built, so it wouldn’t need to do it again. If you need to rebuild (upgrading versions, changing plugins), then run docker-compose build, then run it again with docker-compose up -d.


i will use this thread as a guide in the future, i think that people could use it too in case they don’t understand like me ahah.
Thanks to everyone for your time and your help.