Extending Caddy

Matt Holt edited this page Jul 18, 2016 · 13 revisions

Join the Caddy Community Forum to chat with other Caddy developers!

Caddy can be extended with plugins.

Plugins are flexible ways to add missing functionality to Caddy. Plugins can:

  • 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

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.

How to Write a Caddy Plugin

There are different types of plugins, but the process of creating and registering one is the same.

Start a new Go package with an init function. Then register your plugin. The registration function you use depends on the kind of plugin:

import "github.com/mholt/caddy"

func init() {
    // register a "generic" plugin, like a directive/middleware
    caddy.RegisterPlugin("name", myPlugin)

    // register a plugin that can load the Caddyfile when Caddy starts
    caddy.RegisterCaddyfileLoader("name", myLoader)

    // register a plugin that implements an entire server type
    // for use with Caddy
    caddy.RegisterServerType("name", myServerType)
}

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:

import _ "your/plugin/package/path/here"

Specific Instructions

Learn how to write a specific kind of Caddy plugin.

Don't forget: the best documentation is the godoc and the code itself!

Adding Your Plugin to the Caddy Web Site

Follow these instructions to add your plugin to the Caddy download page.