# Configuration Reference: [Product name] [version]

> Complete list of the settings that control [Product name], how they are
> loaded and how they are validated. Based on common industry practice
> for configuration reference documentation. Replace every `[bracketed]`
> value and every row marked *Example*.

<!--
Guidance: How to use this template
- This page lists facts. It does not recommend values for a particular
  situation; link to the tuning or how-to guides for that.
- Every setting row uses the same columns: key, type, default, allowed
  values, environment variable, description, since version.
- Generate the tables from the schema or code where possible so the page
  cannot drift from the software. Hand-written pages need a check in CI.
- Group settings the way they are grouped in the file, then sort
  alphabetically inside each group.
-->

| Field | Value |
|---|---|
| Product version | [4.2.0] |
| Configuration schema version | [3] |
| Owner | [@platform-team] |
| Status | [Draft / Approved] |
| Last updated | YYYY-MM-DD |

## 1. Sources and precedence

<!-- Guidance: List every place a value can come from and the order in which they override each other. Ambiguous precedence causes the hardest configuration bugs. -->

[Product name] reads configuration from four sources. When the same
setting is defined in more than one place, the source higher in this
list wins:

| Rank | Source | Example | Notes |
|---|---|---|---|
| 1 (highest) | Command-line flag | `--server.port=9090` | Applies to this process only |
| 2 | Environment variable | `APP_SERVER_PORT=9090` | Prefix `APP_`, dots become underscores, upper case |
| 3 | Configuration file | `server.port: 9090` | First file found, see 2 |
| 4 (lowest) | Built-in default | `8080` | Listed in the tables below |

```mermaid
flowchart LR
    D["Defaults"] --> F["Config file"] --> E["Environment"] --> C["Flags"] --> R["Effective configuration"]
```

To see the effective value and where it came from, run
`[app] config show --origin`. Secrets are masked in the output.

## 2. File location and format

<!-- Guidance: Give the search order for the file, the supported formats and a minimal valid example. -->

The first file found in this order is used; others are ignored:

1. The path in `--config` or `APP_CONFIG`.
2. `./app.yaml` in the working directory.
3. `/etc/app/app.yaml` (Windows: `%ProgramData%\App\app.yaml`).

YAML 1.2 and TOML 1.0 are supported; the format is chosen from the file
extension. Unknown keys are rejected so that typos are not silently
ignored. A complete example with defaults:

```yaml
schema_version: 3
server:
  host: 0.0.0.0
  port: 8080
  request_timeout: 30s
database:
  url: ${DATABASE_URL}
  max_connections: 20
cache:
  enabled: true
  ttl: 5m
logging:
  level: info
  format: json
```

`${NAME}` is replaced with the value of environment variable `NAME` at
load time; a missing variable is a validation error.

## 3. Value types

<!-- Guidance: Define each type once so the tables can stay short. -->

| Type | Format | Examples |
|---|---|---|
| string | UTF-8 text | `"eu-west-1"` |
| integer | Whole number, optional `_` separators | `20`, `10_000` |
| boolean | `true` or `false` (also `1`/`0` in environment variables) | `true` |
| duration | Number with unit `ms`, `s`, `m`, `h` | `500ms`, `30s`, `5m` |
| size | Number with unit `B`, `KB`, `MB`, `GB` (base 1024) | `64MB` |
| enum | One of the listed values, case-sensitive | `info` |
| secret | String that is masked in logs and output | `${DATABASE_URL}` |

## 4. Settings

<!-- Guidance: One table per group. Each row is complete; never leave "Default" empty. Use "none (required)" when there is no default. -->

### 4.1 server

| Key | Type | Default | Allowed values | Environment variable | Description | Since |
|---|---|---|---|---|---|---|
| `server.host` | string | `0.0.0.0` | IPv4 or IPv6 address | `APP_SERVER_HOST` | Interface to listen on | 1.0 |
| `server.port` | integer | `8080` | 1 to 65535 | `APP_SERVER_PORT` | TCP port for HTTP traffic | 1.0 |
| `server.request_timeout` | duration | `30s` | 1s to 10m | `APP_SERVER_REQUEST_TIMEOUT` | Maximum time to handle one request | 2.1 |
| `server.max_body_size` | size | `10MB` | 1KB to 1GB | `APP_SERVER_MAX_BODY_SIZE` | Largest accepted request body | 3.0 |

### 4.2 database

| Key | Type | Default | Allowed values | Environment variable | Description | Since |
|---|---|---|---|---|---|---|
| `database.url` | secret | none (required) | `postgres://` URL | `APP_DATABASE_URL` | Connection string including credentials | 1.0 |
| `database.max_connections` | integer | `20` | 1 to 500 | `APP_DATABASE_MAX_CONNECTIONS` | Pool size per process | 1.0 |
| `database.statement_timeout` | duration | `15s` | 100ms to 5m | `APP_DATABASE_STATEMENT_TIMEOUT` | Cancels slower queries | 3.2 |

### 4.3 cache

| Key | Type | Default | Allowed values | Environment variable | Description | Since |
|---|---|---|---|---|---|---|
| `cache.enabled` | boolean | `true` | `true`, `false` | `APP_CACHE_ENABLED` | Turns the response cache on or off | 2.0 |
| `cache.ttl` | duration | `5m` | 0s to 24h | `APP_CACHE_TTL` | Time an entry stays valid; `0s` disables expiry | 2.0 |
| `cache.max_size` | size | `256MB` | 16MB to 16GB | `APP_CACHE_MAX_SIZE` | Memory limit for the cache | 4.0 |

### 4.4 logging

| Key | Type | Default | Allowed values | Environment variable | Description | Since |
|---|---|---|---|---|---|---|
| `logging.level` | enum | `info` | `debug`, `info`, `warn`, `error` | `APP_LOGGING_LEVEL` | Minimum severity written | 1.0 |
| `logging.format` | enum | `json` | `json`, `text` | `APP_LOGGING_FORMAT` | Output format | 1.4 |
| [key] | [type] | [default] | [allowed] | [ENV_VAR] | [Description] | [x.y] |

## 5. Changes at runtime

<!-- Guidance: Say which settings can change without a restart and how to trigger a reload. -->

Settings marked with a reload flag in `config show --origin` can be
changed without restarting: edit the file and send `SIGHUP` or call
`POST /admin/reload`. Currently reloadable: `logging.level`,
`cache.ttl`, `server.request_timeout`. All other changes need a restart.

## 6. Deprecated and removed settings

<!-- Guidance: Keep every deprecated key until it is removed, with its replacement and the removal version. Readers upgrading from old versions rely on this table. -->

| Key | Status | Replacement | Deprecated in | Removed in | Behaviour now |
|---|---|---|---|---|---|
| `db.pool` | Removed | `database.max_connections` | 2.0 | 4.0 | Startup error |
| `server.timeout` | Deprecated | `server.request_timeout` | 3.0 | [5.0] | Value used, warning logged |
| `cache.size_mb` | Deprecated | `cache.max_size` | 4.0 | [5.0] | Converted, warning logged |
| [old key] | [Deprecated / Removed] | [new key] | [x.y] | [x.y] | [Behaviour] |

## 7. Validation

<!-- Guidance: Explain when validation runs, what it checks and what an error looks like, so readers can fix problems quickly. -->

Configuration is validated at startup and on every reload. An invalid
configuration stops startup; an invalid reload is rejected and the
running configuration stays in place. Run the same checks before
deploying:

```bash
app config validate --config ./app.yaml
```

Checks performed:

- Every key is known for the declared `schema_version`.
- Every value has the right type and is inside its allowed range.
- Required settings without defaults are present.
- Referenced environment variables exist.
- Cross-field rules hold, for example
  $\text{database.max\_connections} \times \text{instances} \le$ the
  database server's connection limit (checked when `--instances` is given).

Example error output (exit status 2):

```text
app.yaml:7:20 database.max_connections: 900 is above the maximum of 500
app.yaml:12:10 logging.level: "verbose" is not one of debug, info, warn, error
```

## 8. Related documents

<!-- Guidance: Link to the documents that use or explain these settings, so this page can stay purely factual. -->

- [Installation Guide]: where the file is created during setup.
- [Administrator Guide]: recommended production values and tuning.
- [Changelog]: settings added, changed or deprecated per release.

## Standard and licence note

Based on common industry practice for configuration reference
documentation, including layered precedence of flags, environment
variables, files and defaults. Template licence: MIT.