# 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 ` | config file path | | `-localdb ` | 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 ` | record server migrations up to `` 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.