05 — Configuration and Environment

File Paths

SQLite database (`qfs.db`)

OS	Default path
macOS	`~/Library/Application Support/QuoteForge/qfs.db`
Linux	`$XDG_STATE_HOME/quoteforge/qfs.db` or `~/.local/state/quoteforge/qfs.db`
Windows	`%LOCALAPPDATA%\QuoteForge\qfs.db`

Override: -localdb <path> or QFS_DB_PATH.

config.yaml

Searched in the same user-state directory as qfs.db by default. If the file does not exist, it is created automatically. If the format is outdated, it is automatically migrated to the runtime format (server + logging sections only).

Override: -config <path> or QFS_CONFIG_PATH.

Important: config.yaml is a runtime user file — it is not stored in the repository. config.example.yaml is the only config template in the repo.

Local encryption key

Saved MariaDB credentials in SQLite are encrypted with:

QUOTEFORGE_ENCRYPTION_KEY if explicitly provided, otherwise
an application-managed random key file stored at <state dir>/local_encryption.key.

Rules:

The key file is created automatically with mode 0600.
The key file is not committed and is not included in normal backups.
Restoring qfs.db on another machine requires re-entering DB credentials unless the key file is migrated separately.

config.yaml Structure

server:
  host: "0.0.0.0"
  port: 8080
  mode: "release"   # release | debug

logging:
  level: "info"     # debug | info | warn | error
  format: "json"    # json | text
  output: "stdout"  # stdout | stderr | /path/to/file

backup:
  time: "00:00"     # HH:MM in local time

Environment Variables

Variable	Description	Default
`QFS_DB_PATH`	Full path to SQLite DB	OS-specific user state dir
`QFS_STATE_DIR`	State directory (if `QFS_DB_PATH` is not set)	OS-specific user state dir
`QFS_CONFIG_PATH`	Full path to `config.yaml`	OS-specific user state dir
`QFS_BACKUP_DIR`	Root directory for rotating backups	`<db dir>/backups`
`QFS_BACKUP_DISABLE`	Disable automatic backups	—
`QUOTEFORGE_ENCRYPTION_KEY`	Explicit override for local credential encryption key	app-managed key file
`QF_DB_HOST`	MariaDB host	localhost
`QF_DB_PORT`	MariaDB port	3306
`QF_DB_NAME`	Database name	RFQ_LOG
`QF_DB_USER`	DB user	—
`QF_DB_PASSWORD`	DB password	—
`QF_SERVER_PORT`	HTTP server port	8080

QFS_BACKUP_DISABLE accepts: 1, true, yes.

CLI Flags

Flag	Description
`-config <path>`	Path to config.yaml
`-localdb <path>`	Path to SQLite DB
`-reset-localdb`	Reset local DB (destructive!)
`-migrate`	Apply pending migrations and exit
`-version`	Print version and exit

Installation and First Run

Requirements

Go 1.22 or higher
MariaDB 11.x (or MySQL 8.x)
~50 MB disk space

Steps

# 1. Clone the repository
git clone <repo-url>
cd quoteforge

# 2. Apply migrations
go run ./cmd/qfs -migrate

# 3. Start
go run ./cmd/qfs
# or
make run

Application is available at: http://localhost:8080

On first run, /setup opens for configuring the MariaDB connection.

OPS Project Migrator

Migrates quotes whose names start with OPS-xxxx (where x is a digit) into a project named OPS-xxxx.

# Preview first (always)
go run ./cmd/migrate_ops_projects

# Apply
go run ./cmd/migrate_ops_projects -apply

# Apply without interactive confirmation
go run ./cmd/migrate_ops_projects -apply -yes

Docker

docker build -t quoteforge .
docker-compose up -d

3.6 KiB Raw Blame History