diff options
Diffstat (limited to 'caddy.go')
| -rw-r--r-- | caddy.go | 74 |
1 files changed, 49 insertions, 25 deletions
@@ -32,23 +32,44 @@ import ( "github.com/mholt/certmagic" ) -// Config represents a Caddy configuration. It is the -// top of the module structure: all Caddy modules will -// be loaded, starting with this struct. In order to -// be loaded and run successfully, a Config and all its -// modules must be JSON-encodable; i.e. when filling a -// Config struct manually, its JSON-encodable fields -// (the ones with JSON struct tags, usually ending with -// "Raw" if they decode into a separate field) must be -// set so that they can be unmarshaled and provisioned. -// Setting the fields for the decoded values instead -// will result in those values being overwritten at -// unmarshaling/provisioning. +// Config is the top (or beginning) of the Caddy configuration structure. +// Caddy config is expressed natively as a JSON document. If you prefer +// not to work with JSON directly, there are [many config adapters](/docs/config-adapters) +// available that can convert various inputs into Caddy JSON. +// +// Many parts of this config are extensible through the use of Caddy modules. +// Fields which have a json.RawMessage type and which appear as dots (•••) in +// the online docs can be fulfilled by modules in a certain module +// namespace. The docs show which modules can be used in a given place. +// +// Whenever a module is used, its name must be given either inline as part of +// the module, or as the key to the module's value. The docs will make it clear +// which to use. +// +// Generally, all config settings are optional, as it is Caddy convention to +// have good, documented default values. If a parameter is required, the docs +// should say so. +// +// Go programs which are directly building a Config struct value should take +// care to populate the JSON-encodable fields of the struct (i.e. the fields +// with `json` struct tags) if employing the module lifecycle (e.g. Provision +// method calls). type Config struct { - Admin *AdminConfig `json:"admin,omitempty"` - Logging *Logging `json:"logging,omitempty"` - StorageRaw json.RawMessage `json:"storage,omitempty"` - AppsRaw map[string]json.RawMessage `json:"apps,omitempty"` + Admin *AdminConfig `json:"admin,omitempty"` + Logging *Logging `json:"logging,omitempty"` + + // StorageRaw is a storage module that defines how/where Caddy + // stores assets (such as TLS certificates). By default, this is + // the local file system (`caddy.storage.file_system` module). + // If the `XDG_DATA_HOME` environment variable is set, then + // `$XDG_DATA_HOME/caddy` is the default folder. Otherwise, + // `$HOME/.local/share/caddy` is the default folder. + StorageRaw json.RawMessage `json:"storage,omitempty" caddy:"namespace=caddy.storage inline_key=module"` + + // AppsRaw are the apps that Caddy will load and run. The + // app module name is the key, and the app's config is the + // associated value. + AppsRaw ModuleMap `json:"apps,omitempty" caddy:"namespace="` apps map[string]App storage certmagic.Storage @@ -322,7 +343,7 @@ func run(newCfg *Config, start bool) error { // set up global storage and make it CertMagic's default storage, too err = func() error { if newCfg.StorageRaw != nil { - val, err := ctx.LoadModuleInline("module", "caddy.storage", newCfg.StorageRaw) + val, err := ctx.LoadModule(newCfg, "StorageRaw") if err != nil { return fmt.Errorf("loading storage module: %v", err) } @@ -331,8 +352,8 @@ func run(newCfg *Config, start bool) error { return fmt.Errorf("creating storage value: %v", err) } newCfg.storage = stor - newCfg.StorageRaw = nil // allow GC to deallocate } + if newCfg.storage == nil { newCfg.storage = &certmagic.FileStorage{Path: dataDir()} } @@ -346,12 +367,12 @@ func run(newCfg *Config, start bool) error { // Load, Provision, Validate each app and their submodules err = func() error { - for modName, rawMsg := range newCfg.AppsRaw { - val, err := ctx.LoadModule(modName, rawMsg) - if err != nil { - return fmt.Errorf("loading app module '%s': %v", modName, err) - } - newCfg.apps[modName] = val.(App) + appsIface, err := ctx.LoadModule(newCfg, "AppsRaw") + if err != nil { + return fmt.Errorf("loading app modules: %v", err) + } + for appName, appIface := range appsIface.(map[string]interface{}) { + newCfg.apps[appName] = appIface.(App) } return nil }() @@ -447,7 +468,10 @@ func Validate(cfg *Config) error { return err } -// Duration is a JSON-string-unmarshable duration type. +// Duration can be an integer or a string. An integer is +// interpreted as nanoseconds. If a string, it is a Go +// time.Duration value such as `300ms`, `1.5h`, or `2h45m`; +// valid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, and `h`. type Duration time.Duration // UnmarshalJSON satisfies json.Unmarshaler. |