Files
QuoteForge/bible-local/05-config.md

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.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-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

  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.

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.