More docs about building plugins

Some related feedback on the current docs: as a newish user (I’ve used Caddy 1 pretty trivially, never in production), it’s really hard to understand how to build/use third party modules from the v2 docs. The docs tell you how to code a module (assuming you’ve already set up your dev environment) but don’t really give you any clue how to start.

Now that I’ve found this page and read a bunch of stuff in Github, I think I see how to use these third party modules or maybe build my own, but it took a lot of searching. I think adding some more basic instructions on how to activate third party modules and how to set up a dev environment to build your own would be really helpful.

We do have a few docs pages for this; the install page links to the download page which links to the build from source page, all of which are at the top-left nav of the documentation under the “Get Caddy” section.

Currently, it contains this:

The xcaddy command is the easiest way to build Caddy with version information and/or plugins.
https://caddyserver.com/docs/build#xcaddy

There is more information on usage in that doc.

What’s the best place, do you think, to put these docs so people can discover them easier?

I’d have expected to find some links from the modules page (https://caddyserver.com/docs/modules/) and from the Extending Caddy page: https://caddyserver.com/docs/extending-caddy.

Maybe it should have occurred to me that you’d have to build Caddy from source to create / use third-party modules, but it didn’t. (Maybe building/installing apache modules separately back in the day colored my expectations).

It is also not clear from the “building from source” page that xcaddy is the way to start building your own module.

Sorry, I may have given the wrong impression there - xcaddy isn’t how you start building your module, although it might be how you plug it in while iterating it.

Yes, to produce a binary with your altered/added code, you will need to build the binary yourself.

As for starting, well… That’s a lot more open ended, but it boils down to opening up a project folder, making some .go files, and implementing a caddy.Module interface: https://caddyserver.com/docs/extending-caddy#module-basics

The rest of it is even more open-ended, because at that point the sky is just about the limit. You might want to look at other published third-party modules as sources of inspiration, but it’s naturally going to be pretty self-driven once you start literally writing your own code.

That’s a good point on the modules page - although it only lists core modules (built directly into the Caddy source code), it might not hurt to have some information here, and also in the Extending Caddy doc somewhere.

Ok, now I feel like I didn’t understand it as well as I thought I did. :slight_smile: The template helps me understand what the code might look like, and I assume I can just create a go directory somewhere with the module code, but if I’m not using xcaddy to point at that module than I’m not sure how it’s intended to work.

I get now that you add Caddy modules by building from source & including those modules, and I feel like I get how the basic configuration of modules works. It would certainly be helpful to provide some data about the types of modules that can exist - I see that there are authentication modules and middleware modules, but there’s nothing really about how they’re designed or intended to work (I’m intentionally not reading the v1 docs here).

Anyway, those are just first impressions from someone who hasn’t used Caddy much but has built production systems in Go. Hope it’s helpful. I may try building a module this week, if I do I’ll try to provide some more feedback.

Oops, sorry, I thought this question was about building with plugins, not building plugins.

I’ll be expanding the Extending Caddy section of our documentation soon-ish.