Add Configuration

Configuration.md

@@ -0,0 +1,76 @@
+# Configuration
+ 
+The engine is configured entirely through environment variables. Copy `.env.example` to `.env` to get started.
+ 
+---
+ 
+## Environment Variables
+ 
+| Variable | Default | Description |
+|---|---|---|
+| `DB_PATH` | `fpa.db` | Path to the SQLite database file. Use `:memory:` to run entirely in-memory (useful for tests or ephemeral environments). |
+| `PORT` | `8080` | TCP port the HTTP server listens on. |
+ 
+---
+ 
+## .env.example
+ 
+```env
+DB_PATH=fpa.db
+PORT=8080
+```
+ 
+---
+ 
+## In-Memory Mode
+ 
+For tests or CI pipelines where you don't want a file left on disk:
+ 
+```env
+DB_PATH=:memory:
+```
+ 
+The schema is still applied via auto-migration on startup. Data is lost when the process exits.
+ 
+---
+ 
+## HTTP Server Timeouts
+ 
+Timeouts are hardcoded in `main.go` and are not currently configurable via environment variables:
+ 
+| Timeout | Value | Purpose |
+|---|---|---|
+| `ReadTimeout` | 10s | Maximum time to read the full request |
+| `WriteTimeout` | 30s | Maximum time to write the full response (set higher to allow for large variance reports) |
+| `IdleTimeout` | 120s | Maximum time to keep an idle keep-alive connection open |
+ 
+---
+ 
+## Logging
+ 
+The engine uses Go's `log/slog` with a JSON handler writing to stdout. All log entries are structured JSON, suitable for ingestion by log aggregators like Loki, Datadog, or CloudWatch.
+ 
+Example log lines:
+ 
+```json
+{"time":"2026-03-21T08:16:00Z","level":"INFO","msg":"server starting","port":"8080","db":"fpa.db"}
+{"time":"2026-03-21T08:16:05Z","level":"ERROR","msg":"migration failed","error":"..."}
+```
+ 
+Log level is not currently configurable — the logger runs at INFO.
+ 
+---
+ 
+## Deployment
+ 
+Because the engine compiles to a single binary with no runtime dependencies (SQLite is a pure-Go implementation), deployment is straightforward:
+ 
+```bash
+# Build
+go build -o fpa-engine ./main.go
+ 
+# Run
+DB_PATH=/data/fpa.db PORT=8080 ./fpa-engine
+```
+ 
+It can be containerised, run as a systemd service, or deployed to any platform that can run a Go binary. No Node, Python, or system SQLite library is required.