142 lines
3.6 KiB
Markdown
142 lines
3.6 KiB
Markdown
# 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:
|
|
|
|
1. `QUOTEFORGE_ENCRYPTION_KEY` if explicitly provided, otherwise
|
|
2. 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
|
|
|
|
```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 | — |
|
|
| `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
|
|
|
|
```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
|
|
```
|