# 05 - Config

## Runtime files

| Artifact | Default location |
| --- | --- |
| `qfs.db` | OS-specific user state directory |
| `config.yaml` | same state directory as `qfs.db` |
| `local_encryption.key` | same state directory as `qfs.db` |
| `backups/` | next to `qfs.db` unless overridden |

The runtime state directory can be overridden with `QFS_STATE_DIR`.
Direct paths can be overridden with `QFS_DB_PATH` and `QFS_CONFIG_PATH`.

## Runtime config shape

Runtime keeps `config.yaml` intentionally small:

```yaml
server:
  host: "127.0.0.1"
  port: 8080
  mode: "release"
  read_timeout: 30s
  write_timeout: 30s

backup:
  time: "00:00"

logging:
  level: "info"
  format: "json"
  output: "stdout"
```

Rules:
- QuoteForge creates this file automatically if it does not exist;
- startup rewrites legacy config files into this minimal runtime shape;
- startup normalizes any `server.host` value to `127.0.0.1` before saving the runtime config;
- `server.host` must stay on loopback.

Saved MariaDB credentials do not live in `config.yaml`.
They are stored in SQLite and encrypted with `local_encryption.key` unless `QUOTEFORGE_ENCRYPTION_KEY` overrides the key material.

## Environment variables

| Variable | Purpose |
| --- | --- |
| `QFS_STATE_DIR` | override runtime state directory |
| `QFS_DB_PATH` | explicit SQLite path |
| `QFS_CONFIG_PATH` | explicit config path |
| `QFS_BACKUP_DIR` | explicit backup root |
| `QFS_BACKUP_DISABLE` | disable rotating backups |
| `QUOTEFORGE_ENCRYPTION_KEY` | override encryption key |
| `QF_SERVER_PORT` | override HTTP port |

`QFS_BACKUP_DISABLE` accepts `1`, `true`, or `yes`.

## CLI flags

| Flag | Purpose |
| --- | --- |
| `-config <path>` | config file path |
| `-localdb <path>` | SQLite path |
| `-reset-localdb` | destructive local DB reset |
| `-migrate` | apply server migrations and exit |
| `-version` | print app version and exit |

## First run

1. runtime ensures `config.yaml` exists;
2. runtime opens the local SQLite database;
3. if no stored MariaDB credentials exist, `/setup` is served;
4. after setup, runtime works locally and sync uses saved DB settings in the background.