Cutlery/caddy
1
0
Fork 0
mirror of https://github.com/caddyserver/caddy.git synced 2025-07-09 03:04:57 -04:00
Code Issues Actions Packages Projects Releases Wiki Activity

Updated Extending Caddy (markdown)

Matt Holt 2017-04-18 18:12:40 -06:00
parent c42eb7cf2e
commit 574773f723
1 changed files with 38 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
Extending-Caddy.md

@ -1,29 +1,36 @@
**[Join the Caddy Community Forum](https://forum.caddyserver.com) to chat with other Caddy developers!**
Caddy can be extended with _plugins_.
Caddy can be extended with _plugins_. Plugins add missing functionality to Caddy. They are "plugged in" at compile-time.
Plugins are flexible ways to add missing functionality to Caddy. Plugins can:
Almost everything in Caddy is a plugin. The HTTP server is a plugin. Caddy's advanced TLS features are plugins. Every single directive you type in the Caddyfile is a plugin.
- Implement an entire server type (HTTP, for instance)
- Customize how the Caddyfile is loaded
- Run functions when servers are started, restarted, or stopped (including background services / goroutines)
- Define new directives for the Caddyfile
- Wire up ACME DNS challenge solvers for your favorite DNS providers
Some plug into Caddy core, while others plug into a specific server type. Some plugins even plug into other plugins (for example, DNS providers plug into the `tls` plugin). Caddy ships with certain plugins by default: the HTTP server with its standard directives and the standard Caddyfile loaders.
Notice that Caddy's HTTP server is a _plugin_. Caddy's advanced TLS features are _plugins_. The different ways Caddy loads the Caddyfile are all _plugins_. And every single directive you type into the Caddyfile is a _plugin_.
There are different kinds of plugins you can write:
- **[Server Types](https://github.com/mholt/caddy/wiki/Writing-a-Plugin:-Server-Type)** - A kind of server that Caddy can run (HTTP and DNS for example)
- **[Directives](https://github.com/mholt/caddy/wiki/Writing-a-Plugin:-Directives)** - A directive for the Caddyfile
- **[HTTP Middleware](https://github.com/mholt/caddy/wiki/Writing-a-Plugin:-HTTP-Middleware)** - A function that handles HTTP requests, usually invoked by a Caddyfile directive
- **[Caddyfile Loader](https://github.com/mholt/caddy/wiki/Writing-a-Plugin:-Caddyfile-Loader)** - Customize how the Caddyfile is loaded
- **[DNS Provider](https://github.com/mholt/caddy/wiki/Writing-a-Plugin:-DNS-Provider)** - Make ACME's DNS challenge compatible with your DNS provider
- **Listener Middleware** - Wrap a net.Listener with your own Listener to do something at the transport or protocol layer
- **Event Hook** - Execute a function when the Caddy process emits certain events
## How to Write a Caddy Plugin
The links above will show you how to write those kinds of plugins, but always refer to the [godoc](https://godoc.org/github.com/mholt/caddy) and the [code base itself](https://sourcegraph.com/github.com/mholt/caddy) when you have questions!
There are different types of plugins, but the process of creating and registering one is the same.
## 5 Steps to Make a Caddy Plugin
Start a new Go package with an init function. Then register your plugin. The registration function you use depends on the kind of plugin:
Even though there are different kinds of plugins, the process of creating one is roughly the same for all.
### 1. Create a package and register your plugin.
Start a new Go package with an init function and register your plugin with Caddy or the server type or the other plugin that uses it. The registration function you use depends on the kind of plugin. A few are shown here:
```go
import "github.com/mholt/caddy"
func init() {
// register a "generic" plugin, like a directive/middleware
// register a "generic" plugin, like a directive or middleware
caddy.RegisterPlugin("name", myPlugin)
// register a plugin that can load the Caddyfile when Caddy starts
@ -32,33 +39,38 @@ func init() {
// register a plugin that implements an entire server type
// for use with Caddy
caddy.RegisterServerType("name", myServerType)
// register a function that runs when Caddy emits events
caddy.RegisterEventHook("eventName", myHookFn)
// add a function that wraps listeners for the HTTP server
// (it's more common for a directive to call this rather than a standalone plugin)
httpserver.AddListenerMiddleware(myListenerMiddleware)
// ... there are others. See the godoc.
}
```
Every plugin must have a name, and, when applicable, the name must be unique for that server type.
Every plugin must have a name and, when applicable, the name must be unique for that server type.
To plug your plugin into Caddy, import it. This is usually done in [run.go](https://github.com/mholt/caddy/blob/master/caddy/caddymain/run.go):
### 2. Plug in your plugin.
To plug your plugin into Caddy, import it. This is usually done near the top of [run.go](https://github.com/mholt/caddy/blob/master/caddy/caddymain/run.go):
```go
import _ "your/plugin/package/path/here"
```
### 3. Test, test, test!
### Specific Instructions
[Write tests.](https://golang.org/pkg/testing) Get good coverage where possible, and make sure your assertions test what you think they are testing! Use `go vet` and `go test -race` to ensure your plugin is as error-free as possible.
Learn how to write a specific kind of Caddy plugin.
### 4. Add your plugin to the Caddy web site.
- [A new directive for the Caddyfile](https://github.com/mholt/caddy/wiki/Writing-a-Plugin:-Directives)
- [A middleware for the HTTP server](https://github.com/mholt/caddy/wiki/Writing-a-Plugin:-HTTP-Middleware)
- [A different way to load the Caddyfile](https://github.com/mholt/caddy/wiki/Writing-a-Plugin:-Caddyfile-Loader)
- [An entire server type](https://github.com/mholt/caddy/wiki/Writing-a-Plugin:-Server-Type)
- [A DNS provider for ACME's DNS challenge](https://github.com/mholt/caddy/wiki/Writing-a-Plugin:-DNS-Provider)
Make it easy for others to find and use your plugin! [Follow these instructions](https://github.com/mholt/caddy/wiki/Publishing-a-Plugin-to-the-Download-Page) to add your plugin to Caddy's download page.
### 5. Maintain your plugin.
**Don't forget: the best documentation is the [godoc](https://godoc.org/github.com/mholt/caddy) and the code itself!**
People will use plugins that are useful, clearly documented, easy to use, and maintained by their owner.
## Adding Your Plugin to the Caddy Web Site
[Follow these instructions](https://github.com/mholt/caddy/wiki/Publishing-a-Plugin-to-the-Download-Page) to add your plugin to the Caddy download page.
And congratulations, you're a Caddy plugin author!