Module System

Caddy’s module system is the foundation of its extensibility. Every component in Caddy—from HTTP handlers to TLS certificate issuers—is implemented as a module. This architecture allows you to extend Caddy with custom functionality or use third-party modules.

What is a Module?

A module is any Go type that implements the Module interface:

modules.go:54-60

type Module interface {
    // This method indicates that the type is a Caddy module.
    // The returned ModuleInfo must have both a name and a constructor function.
    CaddyModule() ModuleInfo
}

Module Information

Each module must provide metadata about itself:

modules.go:62-77

type ModuleInfo struct {
    // ID is the "full name" of the module.
    // It must be unique and properly namespaced.
    ID ModuleID

    // New returns a pointer to a new, empty instance of the module's type.
    // This method must not have any side-effects.
    New func() Module
}

Module Namespaces

Module IDs follow a hierarchical naming convention:

modules.go:79-98

// ModuleID is a string that uniquely identifies a Caddy module.
// It consists of dot-separated labels which form a simple hierarchy.
//
// Examples of valid IDs:
// - http
// - http.handlers.file_server
// - caddy.logging.encoders.json
type ModuleID string

Namespace structure: <namespace>.<name>Top-level modules (apps) have no namespace, just a name like http or tls.

Common Namespaces

Namespace	Purpose	Example Modules
(empty)	Apps	`http`, `tls`, `pki`
`http.handlers`	HTTP handlers	`file_server`, `reverse_proxy`, `rewrite`
`http.matchers`	Request matchers	`host`, `path`, `header`
`tls.issuance`	Certificate issuers	`acme`, `internal`, `zerossl`
`tls.certificates`	Cert loaders	`automate`, `load_files`, `load_folders`
`caddy.storage`	Storage backends	`file_system`, `consul`, `s3`
`caddy.logging.encoders`	Log encoders	`json`, `console`, `logfmt`

Module Registration

Modules must be registered before Caddy can use them:

modules.go:130-161

func RegisterModule(instance Module) {
    mod := instance.CaddyModule()

    if mod.ID == "" {
        panic("module ID missing")
    }
    if mod.ID == "caddy" || mod.ID == "admin" {
        panic(fmt.Sprintf("module ID '%s' is reserved", mod.ID))
    }
    if mod.New == nil {
        panic("missing ModuleInfo.New")
    }
    if val := mod.New(); val == nil {
        panic("ModuleInfo.New must return a non-nil module instance")
    }

    modulesMu.Lock()
    defer modulesMu.Unlock()

    if _, ok := modules[string(mod.ID)]; ok {
        panic(fmt.Sprintf("module already registered: %s", mod.ID))
    }
    modules[string(mod.ID)] = mod
}

Module registration typically happens in init() functions and will panic if:

The module ID is empty or reserved
The constructor function is nil
The module is already registered

Example Registration

package myhandler

import "github.com/caddyserver/caddy/v2"

func init() {
    caddy.RegisterModule(Handler{})
}

type Handler struct {
    // Your fields here
}

func (Handler) CaddyModule() caddy.ModuleInfo {
    return caddy.ModuleInfo{
        ID:  "http.handlers.my_handler",
        New: func() caddy.Module { return new(Handler) },
    }
}

Module Lifecycle

When a module is loaded, it goes through several phases:

Instantiation

Caddy calls ModuleInfo.New() to create a new instance:

context.go:369

val := modInfo.New()

Unmarshaling

The module’s configuration is unmarshaled into the instance:

context.go:382-387

if len(rawMsg) > 0 {
    err := StrictUnmarshalJSON(rawMsg, &val)
    if err != nil {
        return nil, fmt.Errorf("decoding module config: %s: %v", modInfo, err)
    }
}

Provisioning

If the module implements Provisioner, its Provision() method is called:

modules.go:288-298

type Provisioner interface {
    Provision(Context) error
}

context.go:418-430

if prov, ok := val.(Provisioner); ok {
    err = prov.Provision(ctx)
    if err != nil {
        // Cleanup on error
        if cleanerUpper, ok := val.(CleanerUpper); ok {
            cleanerUpper.Cleanup()
        }
        return nil, fmt.Errorf("provision %s: %v", modInfo, err)
    }
}

Validation

If the module implements Validator, its Validate() method is called:

modules.go:300-307

type Validator interface {
    Validate() error
}

context.go:433-444

if validator, ok := val.(Validator); ok {
    err = validator.Validate()
    if err != nil {
        // Cleanup on error
        if cleanerUpper, ok := val.(CleanerUpper); ok {
            cleanerUpper.Cleanup()
        }
        return nil, fmt.Errorf("%s: invalid configuration: %v", modInfo, err)
    }
}

Usage

The module is now ready to be used. It’s typically type-asserted to a specific interface expected by the host module.

Cleanup

When the config is unloaded, if the module implements CleanerUpper, its Cleanup() method is called:

modules.go:309-317

type CleanerUpper interface {
    Cleanup() error
}

context.go:75-83

for modName, modInstances := range newCtx.moduleInstances {
    for _, inst := range modInstances {
        if cu, ok := inst.(CleanerUpper); ok {
            err := cu.Cleanup()
            if err != nil {
                log.Printf("[ERROR] %s (%p): cleanup: %v", modName, inst, err)
            }
        }
    }
}

Loading Modules

Caddy provides the LoadModule method to load modules from configuration:

context.go:181

func (ctx Context) LoadModule(structPointer any, fieldName string) (any, error)

Supported Field Types

The LoadModule method supports several raw module types:

json.RawMessage

For a single module:

type MyConfig struct {
    HandlerRaw json.RawMessage `json:"handler,omitempty" caddy:"namespace=http.handlers inline_key=handler"`
}

val, err := ctx.LoadModule(cfg, "HandlerRaw")
handler := val.(caddyhttp.MiddlewareHandler)

[]json.RawMessage

For a list of modules:

type MyConfig struct {
    HandlersRaw []json.RawMessage `json:"handlers,omitempty" caddy:"namespace=http.handlers inline_key=handler"`
}

val, err := ctx.LoadModule(cfg, "HandlersRaw")
handlers := val.([]any)
for _, h := range handlers {
    handler := h.(caddyhttp.MiddlewareHandler)
}

map[string]json.RawMessage (ModuleMap)

For a map where keys are module names:

type MyConfig struct {
    AppsRaw caddy.ModuleMap `json:"apps,omitempty" caddy:"namespace="`
}

val, err := ctx.LoadModule(cfg, "AppsRaw")
apps := val.(map[string]any)
for name, app := range apps {
    // Use the app
}

Struct Tags

Modules are configured using struct tags:

modules.go:319-336

func ParseStructTag(tag string) (map[string]string, error) {
    results := make(map[string]string)
    pairs := strings.Split(tag, " ")
    for i, pair := range pairs {
        if pair == "" {
            continue
        }
        before, after, isCut := strings.Cut(pair, "=")
        if !isCut {
            return nil, fmt.Errorf("missing key in '%s' (pair %d)", pair, i)
        }
        results[before] = after
    }
    return results, nil
}

Required tags:

namespace - The module namespace to search (e.g., http.handlers)

Optional tags:

inline_key - The JSON key containing the module name (e.g., handler)

When using ModuleMap, the map key IS the module name, so inline_key is not needed.

Creating Custom Modules

Here’s a complete example of a custom HTTP handler module:

Define the Module

package greeting

import (
    "fmt"
    "net/http"
    
    "github.com/caddyserver/caddy/v2"
    "github.com/caddyserver/caddy/v2/modules/caddyhttp"
    "go.uber.org/zap"
)

func init() {
    caddy.RegisterModule(Greeting{})
}

type Greeting struct {
    Message string `json:"message,omitempty"`
    logger  *zap.Logger
}

func (Greeting) CaddyModule() caddy.ModuleInfo {
    return caddy.ModuleInfo{
        ID:  "http.handlers.greeting",
        New: func() caddy.Module { return new(Greeting) },
    }
}

Implement Provisioner

func (g *Greeting) Provision(ctx caddy.Context) error {
    g.logger = ctx.Logger()
    if g.Message == "" {
        g.Message = "Hello, World!"
    }
    return nil
}

Implement Validator

func (g Greeting) Validate() error {
    if len(g.Message) > 1000 {
        return fmt.Errorf("message too long (max 1000 chars)")
    }
    return nil
}

Implement Handler Interface

func (g Greeting) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error {
    g.logger.Info("serving greeting",
        zap.String("message", g.Message),
        zap.String("remote", r.RemoteAddr),
    )
    w.Write([]byte(g.Message))
    return nil
}

Add Interface Guards

var (
    _ caddy.Provisioner              = (*Greeting)(nil)
    _ caddy.Validator                = (*Greeting)(nil)
    _ caddyhttp.MiddlewareHandler    = (*Greeting)(nil)
)

Module Discovery

Caddy provides functions to discover registered modules:

modules.go:195-242

// GetModules returns all modules in the given scope/namespace
func GetModules(scope string) []ModuleInfo {
    modulesMu.RLock()
    defer modulesMu.RUnlock()

    scopeParts := strings.Split(scope, ".")
    if scope == "" {
        scopeParts = []string{}
    }

    var mods []ModuleInfo
iterateModules:
    for id, m := range modules {
        modParts := strings.Split(id, ".")

        // match only the next level of nesting
        if len(modParts) != len(scopeParts)+1 {
            continue
        }

        // specified parts must be exact matches
        for i := range scopeParts {
            if modParts[i] != scopeParts[i] {
                continue iterateModules
            }
        }

        mods = append(mods, m)
    }

    // make return value deterministic
    sort.Slice(mods, func(i, j int) bool {
        return mods[i].ID < mods[j].ID
    })

    return mods
}

Examples:

// Get all HTTP handler modules
handlers := caddy.GetModules("http.handlers")

// Get all top-level app modules  
apps := caddy.GetModules("")

// Get all TLS certificate issuers
issuers := caddy.GetModules("tls.issuance")

Best Practices

Always Use Pointers

Module constructors should return pointers:

New: func() caddy.Module { return new(MyModule) }

Validate Configuration

Implement Validator to catch configuration errors early:

func (m MyModule) Validate() error {
    if m.Required == "" {
        return fmt.Errorf("required field is empty")
    }
    return nil
}

Clean Up Resources

Implement CleanerUpper if your module allocates resources:

func (m *MyModule) Cleanup() error {
    if m.conn != nil {
        return m.conn.Close()
    }
    return nil
}

Use Context Logger

Get a properly-configured logger from the context:

func (m *MyModule) Provision(ctx caddy.Context) error {
    m.logger = ctx.Logger()
    return nil
}

Add Interface Guards

Use compile-time interface guards to catch mistakes:

var (
    _ caddy.Provisioner = (*MyModule)(nil)
    _ caddy.Validator   = (*MyModule)(nil)
)

Common Pitfalls:

Forgetting to register the module in init()
Not returning pointers from constructors
Performing I/O in Provision() that should be in Start()
Not cleaning up resources in Cleanup()

Get Started

Core Concepts

Configuration

Guides

Module System

What is a Module?

Module Information

Module Namespaces

Common Namespaces

Module Registration

Example Registration

Module Lifecycle

Loading Modules

Supported Field Types

Struct Tags

Creating Custom Modules

Module Discovery

Best Practices

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Guides

​What is a Module?

​Module Information

​Module Namespaces

​Common Namespaces

​Module Registration

​Example Registration

​Module Lifecycle

​Loading Modules

​Supported Field Types

​Struct Tags

​Creating Custom Modules

​Module Discovery

​Best Practices

Build docs developers (and LLMs) love

What is a Module?

Module Information

Module Namespaces

Common Namespaces

Module Registration

Example Registration

Module Lifecycle

Loading Modules

Supported Field Types

Struct Tags

Creating Custom Modules

Module Discovery

Best Practices