Tutorial for extending caddy

I’m newbie on golang and has little experience on nginx. I need much more example for How to add module/plugin/extension for caddy.

For example how about add WAF rules?

How to process IP from black list and response JS Challenge or Captcha Challange.

I need more info and tutorial for create such a stuff like this.

But documentation is so simple about how to use and create simple plugin for caddy.

Hi @sweb, welcome to the Caddy community.

Apart from the documentation on extending Caddy (see: Extending Caddy — Caddy Documentation), I haven’t seen any other tutorials / examples.

In v1’s case there’s a corpus of existing open source third party plugins to draw inspiration from, but v2 is still in its early days.

There is a complete HTTP handler module example, which is where I expect you would want to implement a WAF (see: Extending Caddy — Caddy Documentation).

You get the http.Request passed to your ServeHTTP function, which is where the magic happens, so you can do a lot of inspection here based on what the http standard library gives you (see: http package - net/http - pkg.go.dev).


Thanks for reply, my point is showing the abstraction is not good enough for documentation.

Some of example will be good if added.

  • Get/Set/Check cookie
  • Parse QueryString/Path/ and POST form and body data
  • Get Headers of request
  • Set additional Response
  • Modify response
  • Just response different if request is not valid

Be practical and most use cases of most nginx/apache plugins will be great.


Just with auth request new world is open as webserver like nginx:
GitHub - vouch/vouch-proxy: an SSO and OAuth / OIDC login solution for Nginx using the auth_request module

Those questions are more about how to approach web development in Go than being Caddy specific. If you’re already familiar with basics of Go, then you can follow these 2 tutorials sequentially:

If you’re not proficient in Go, then you should take the Go Tour first: A Tour of Go


Just to elaborate a bit further, we benefit from being able to use Golang’s standard http library. This library is incredibly widely used and incredibly widely documented, with tutorials everywhere. Just the godoc alone (see: http package - net/http - pkg.go.dev) is incredibly useful.

So the first few you’re looking for - definitely aren’t specific to Caddy at all. There’s much better literature out there explaining how to interact with those, and we’d be doing their authors and our readers a disservice by trying to recreate those guides and tutorials. As for these parts:

To be clear, there’s no response already built for you when your ServeHTTP function receives the request. It gets the http.Request and a http.ResponseWriter. You can write whatever you want to the ResponseWriter - you are 100% in charge. It’s entirely up to you how you do it - some conventional way (the tutorials linked above are great), or by importing other libs that help with the process, it’s your call. You can do almost literally anything. There’s nothing to modify or change. You get a blank slate.

You want to respond differently if a request is not valid? Time to throw in some conditional statements. Build your “invalid request” response and decide how you want to handle a “valid” request (maybe pass it along to the next handler?).


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