Caddy 1.0.0-beta2 released, and instructions for plugin developers

Some of you have noticed that building Caddy from source (or from the download page!) has been a little difficult lately.

The good news is: building Caddy yourself from source is now much better! It no longer requires using a special build script. And adding plugins no longer requires modifying Caddy’s source code.

We’ve updated the README and developer wiki to include the latest instructions.

We’re transitioning to using Go modules, which is an official dependency management system built into the go tool. They have some really nice features, but a lot of rough edges too, that have made the transition difficult for me and for many of you. But, in the long run, they will offer stable, secure dependency management that will make development and deployment easier and safer.

If you build Caddy from source, please see the updated instructions linked to in the README and wiki pages above. Note that the instructions will change slightly after we tag the stable 1.0 release, and again after Go 1.13 is released. Both the Caddy and Go projects are very much in a transition period right now.

If you use our download page or, be aware that many builds may fail, especially those with plugins. There is not a need to report failed builds/downloads at this time.

The reason many builds fail from our download page is because most plugins do not yet use Go modules, and even if they do, they must require one of the recent beta releases of Caddy. This is because all Caddy plugins depend on Caddy. By default, the Go tool uses the latest non-prerelease version when no version is specified (as is the case for all plugins that are not modules, or for modules that do not explicitly pin a specific version). The latest non-prerelelase version of Caddy is v0.11.5, which does not support Go modules. Thus, it lacks version pinning for its dependencies, some of which have since made incompatible changes. Our vendor folder used to take care of this problem, but we removed the vendor folder since we want to lighten the repo, and modules does the version pinning for us… or at least, it will after the transition. When we tag v1.0.0, modules should resolve that version instead and most builds will begin succeeding. But we won’t be sure until that release! So it’s a chicken-and-egg problem.

In the meantime, remember that Caddy 1.0 will not be a perfect release; not all open bugs will have been fixed, etc. We’re merely demarcating where backwards-incompatible changes will no longer intentionally happen on the same major version tree, and celebrating Caddy’s maturity as a web server.

In summary, please try the beta! You can now download it from our build server (maybe) or from our GitHub releases.


Plugin authors: here is how you can turn your Caddy plugin into a Go module that relies on the current beta release of Caddy, which should allow builds to succeed.

These instructions are derived from the Go wiki about how to define a module. I recommend giving that a solid read (yes, there is lots to read). These instructions assume Mac or Linux.

  1. export GO111MODULE=on

  2. From your plugin’s repo directory, run go mod init. Since it already exists in VCS, it should be able to infer the import path.

  3. Pin the beta version of Caddy, otherwise Go will try to use the “latest” (by which it means “latest non-prerelease tag”, which is confusing, but arguably good behavior). Remember that the “latest” version of Caddy does not have module support yet, so run: go get (or whatever the latest beta is at the time).

  4. Once you are sure that go test ./... succeeds, tag that commit with a version and push it.

  5. Update your plugin on the Caddy website to use that new tag of your plugin. Note that origin/master is no longer a valid version to release on the Caddy site; it has to be a branch, commit hash, or tag. We always recommend tags, especially now with Go modules in the loop.

Hopefully the deploy succeeds.

Remember that after the stable 1.0 tag of Caddy, pinning a specific version will not be strictly necessary, in fact, might not be advisable. I am not sure what using an older Caddy version will do to the size of the binary. :grimacing: In the future, letting Go resolve the latest should be just fine…