Configuration

Configure an application with YAML files, per-environment directories, plugin defaults and SUMMER_ environment variables, and set the keys it needs.

WinterCMS keeps configuration in config/*.php files, per-environment directories and .env. SummerCMS keeps the same shape with YAML files, merged by compass into one tree that you read with dot paths such as app.name.

The config directory#

Each YAML file in the application's config/ directory is a section named after the file, so config/app.yaml provides the app.* keys and config/http.yaml provides http.*:

# config/app.yaml
name: Acme
url: http://127.0.0.1:8080
timezone: Europe/Warsaw

Files for one environment go in config/env/<environment>/ with the same naming, and override the base files. The environment comes from SUMMER_ENV and defaults to production, so a development setup sets SUMMER_ENV=development and keeps its overrides in config/env/development/.

Plugin defaults#

A plugin ships its own defaults embedded in the binary through pact.HasConfig. Its config/config.yaml becomes <plugin id>.<key>, so the posts_per_page key of acme.blog is read as acme.blog.posts_per_page. WinterCMS writes the same key as acme.blog::posts_per_page. The application overrides a plugin default like any other key: put posts_per_page under blog: in config/acme.yaml.

Environment variables#

Any key can be overridden with an environment variable. Take the dot path, replace each dot with a double underscore, upper-case it and prefix SUMMER_:

Key	Variable
`database.dsn`	`SUMMER_DATABASE__DSN`
`app.key`	`SUMMER_APP__KEY`
`admin.jwt.secret`	`SUMMER_ADMIN__JWT__SECRET`

A .env file next to the config/ directory supplies KEY=VALUE lines for variables that are not already set in the real environment. Keep secrets in the environment or in .env, never in committed YAML.

Environment values are strings. Keys that must be numbers, such as http.body_limits.default_bytes, belong in a YAML file.

The layers merge in this order, each overriding the ones before it: plugin defaults, config/*.yaml, config/env/<environment>/*.yaml, SUMMER_ variables, then runtime overrides that a command saved to config/env/<environment>/overrides.yaml.

Keys an application sets#

These are the keys most applications set. Each module's reference page lists all of its keys and their defaults.

Key	Purpose	Reference
`database.dsn`	PostgreSQL connection string. Required by every command that opens the database.	lagoon
`app.key`	Base64 encoding of 32 random bytes, used to encrypt columns. Generate it with `key:generate`.	lagoon
`app.timezone`	Timezone of scheduled commands. Defaults to UTC.	conga
`app.locale`, `app.fallback_locale`	Default and fallback translation locales.	phrasebook
`http.body_limits.default_bytes`, `http.body_limits.upload_bytes`	Request body limits. Required by `serve` and `route:list`.	surf
`http.cors.*`, `http.trusted_proxies`	CORS and the proxies whose forwarded client IP is trusted.	surf
`storage.uploads.bucket_url`	Uploads bucket, `file://` or `mem://`. Required by `serve`.	lagoon
`admin.jwt.secret`	Secret for admin tokens. Required as soon as a plugin registers an admin controller.	cabana
`backend.uri`	Path the admin is served under. Defaults to `/backend`.	cabana
`mail.driver`, `mail.from`, `mail.smtp.*`	Mail delivery: `memory`, `log` or `smtp`.	postcard
`queue.work_in_serve`, `queue.queues.*`	Whether `serve` runs the job worker, and workers per queue.	conga
`realtime.driver`, `realtime.centrifugo.*`	The realtime driver and its Centrifugo settings.	lighthouse
`search.driver`, `search.typesense.*`	The search engine and its Typesense settings.	beachcomber
`push.enabled`, `push.public_key`, `push.private_key`	Web Push with VAPID keys.	flare

Reading configuration in a plugin#

Plugins read configuration from backpack.App.Config, a compass.Config. Use compass.Config.String, compass.Config.Int and compass.Config.Bool for single values, which return the zero value for a missing key, compass.Config.Has to tell a missing key from a zero value, and compass.Config.LoadSection to decode a whole section into a struct.