3.6 KiB
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:
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.hostvalue to127.0.0.1before saving the runtime config; server.hostmust 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-restore <archive.zip> |
restore and verify a server migration snapshot during DBA maintenance |
-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
- runtime ensures
config.yamlexists; - runtime opens the local SQLite database;
- if no stored MariaDB credentials exist,
/setupis served; - 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.
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.