96 lines
3.5 KiB
Markdown
96 lines
3.5 KiB
Markdown
# 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` | reset after mandatory verified backup; refuses unsynced work |
|
|
| `-force-reset-localdb` | with `-reset-localdb`, allow clearing unsynced work; backup remains mandatory |
|
|
| `-migrate` | apply pending server SQL migrations (`migrations/*.sql`) and exit |
|
|
| `-migrate-status` | list server SQL migrations with applied/pending state and exit |
|
|
| `-migrate-baseline <file>` | record server migrations up to `<file>` as applied without running them, 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.
|
|
|
|
`QFS_RESET_LOCAL_DB` is no longer supported. Reset requires an explicit CLI flag
|
|
on each launch. A forced reset still stops if the safety backup cannot be created
|
|
and verified. See [06-backup.md](06-backup.md).
|
|
|
|
## MariaDB TLS
|
|
|
|
`/setup` stores `tls_mode` and `tls_ca_pem` in SQLite `connection_settings`,
|
|
alongside encrypted credentials. Existing and new connections default to
|
|
`preferred`, which encrypts when advertised by MariaDB but can fall back to
|
|
plaintext and does not authenticate the server. `required` mandates encryption
|
|
without verifying the certificate. `verify-ca` requires a PEM CA and validates
|
|
the server certificate chain without checking its hostname. `verify-full`
|
|
validates both chain and hostname, using the supplied PEM or system roots.
|
|
Only the verification modes accept CA input; invalid modes/PEM are rejected.
|
|
Use `verify-full` for authenticated server connections. The setup form tests
|
|
the selected policy before saving. Sync, setup checks and migration tooling
|
|
share the same TLS configuration builder.
|