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

---

## config.yaml Structure

```yaml
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 | — |
| `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_JWT_SECRET` | JWT secret | — |
| `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

```bash
# 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`.

```bash
# 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

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