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 @anon70754465,

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


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.


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


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


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

: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.


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