# 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](/docs/api/compass.md) 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.*`:

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

> [!NOTE]
> The documentation checks every identifier, link and command name it shows against the code, but not configuration keys. The keys on this page are reviewed by hand; the module reference pages are the authority.

## 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.