QuoteForge/bible-local/05-config.md

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