cesnimda/jobtrackingapp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: consolidate repository guides and preserve audit history

Browse Source
This commit is contained in:
cesnimda
2026-09-11 14:22:41 +02:00
parent 115441a409
commit 682a3028bb
404 changed files with 3402 additions and 2621 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/configuration/README.md
+5
View File
@@ -0,0 +1,5 @@
# Configuration
The repository uses layered configuration: `appsettings*.json`, Docker Compose environment mappings, `.env` for local/operator values, and frontend build arguments. [Environment variables](environment-variables.md) is the complete variable index; [environments](environments.md) explains local, test, and production differences.
Never commit real secret values. `NEXT_PUBLIC_*` values are embedded into browser bundles and are public by design.
docs/configuration/environment-variables.md
+114
View File
@@ -0,0 +1,114 @@
# Environment variables
This table covers the variables in `.env.example`, their Docker Compose mappings, and runtime variables read directly by the API, UI, AI service, or test harness. Blank means no repository default; “conditional” means required only when that feature/provider is enabled.
## Database and application
| Variable | Required | Service | Secret | Default | Description |
|---|---|---|---|---|---|
| `DATABASE_PROVIDER` | Production | Compose/API | No | `sqlite` | `sqlite`, `mariadb`, or `mysql`; also selects the backup path. |
| `JOBTRACKER_CONNECTION_STRING` | Conditional | API | Yes | — | Server database connection string; ignored for SQLite. |
| `APP_PUBLIC_BASE_URL` | Production | API/UI | No | — | Canonical external origin for links, callbacks, cookies, billing, and host validation. |
| `APP_VERSION` | No | API | No | — | Release/version metadata. |
| `APP_COMMIT_SHA` | No | API | No | — | Release commit metadata. |
| `APP_BUILD_STAMP` | No | API | No | — | Release build timestamp metadata. |
| `NEXT_PUBLIC_API_BASE_URL` | No | UI build | No | `/api` | Browser-visible API origin; leave blank for nginx same-origin proxy. |
## Authentication, identity, and billing
| Variable | Required | Service | Secret | Default | Description |
|---|---|---|---|---|---|
| `AUTH_JWT_KEY` | Production | API | Yes | — | Local JWT signing key; required when auth is required. |
| `AUTH_ADMIN_EMAIL` | Conditional | API | No | — | Seed/admin account email. |
| `AUTH_ADMIN_PASSWORD` | Conditional | API | Yes | — | Seed/admin account password. |
| `AUTH_ALLOW_REGISTRATION` | No | API | No | `false` | Enables local self-registration. |
| `AUTH_REQUIRE_EMAIL_VERIFICATION` | No | API | No | `true` | Requires verified local-account email before sign-in. |
| `ACCOUNT_DELETION_ENABLED` | No | API | No | `false` | Self-service deletion gate; keep disabled until retention/restore policy is approved. |
| `TURNSTILE_SITE_KEY` | Conditional | API/UI | No | — | Public Turnstile site key. |
| `TURNSTILE_SECRET_KEY` | Conditional | API | Yes | — | Server-side Turnstile verification secret. |
| `AUTH_GOOGLE_CLIENT_ID` | Conditional | API/UI | No | — | Google sign-in client ID. |
| `AUTH_MICROSOFT_CLIENT_ID` | Conditional | API/UI | No | — | Microsoft sign-in client ID. |
| `AUTH_MICROSOFT_TENANT` | No | API/UI | No | `common` | Microsoft sign-in tenant policy; distinct from Graph tenant. |
| `STRIPE_SECRET_KEY` | Conditional | API | Yes | — | Hosted Checkout/portal server key. |
| `STRIPE_PRICE_PREMIUM` | Conditional | API | No | — | Recurring Premium Stripe Price ID (`price_...`). |
| `STRIPE_WEBHOOK_SECRET` | Conditional | API | Yes | — | Signed billing webhook secret. |
## Mail-provider connections
| Variable | Required | Service | Secret | Default | Description |
|---|---|---|---|---|---|
| `GOOGLE_GMAIL_CLIENT_SECRET` | Conditional | API | Yes | — | Gmail OAuth client secret. |
| `MICROSOFT_CLIENT_ID` | Conditional | API | No | — | Microsoft Graph mail application ID; separate from sign-in ID. |
| `MICROSOFT_CLIENT_SECRET` | Conditional | API | Yes | — | Microsoft Graph OAuth secret. |
| `MICROSOFT_TENANT_ID` | Conditional | API | No | — | Graph mailbox tenant; separate from `AUTH_MICROSOFT_TENANT`. |
## AI and document processing
| Variable | Required | Service | Secret | Default | Description |
|---|---|---|---|---|---|
| `AI_SERVICE_BASE_URL` | Docker | API | No | `http://ai-service:8001` | Internal FastAPI service URL. |
| `AI_SERVICE_TOKEN` | Docker/prod | API/AI | Yes | — | Shared backend-to-sidecar token; required by Compose except `/health`. |
| `OLLAMA_BASE_URL` | No | AI | No | `http://ollama:11434` | Ollama endpoint. |
| `OLLAMA_MODEL` | No | AI | No | `qwen2.5:7b` | Local Ollama model. |
| `AI_PROVIDER` | No | API/AI | No | `ollama` | Structured CV provider: `ollama`, `gemini`, or `groq`. |
| `EXTERNAL_AI_ENABLED` | No | API/AI | No | `false` | Administrator gate for external processing. |
| `AI_ROUTING_MODE` | No | API/AI | No | `local_first` | `local_only`, `local_first`, or `external_only`. |
| `EXTERNAL_AI_ALLOWED_TASKS` | No | AI | No | CV task list | Allowlisted external task types. |
| `EXTERNAL_AI_MAX_PROMPT_CHARS` | No | AI | No | `24000` | External prompt-size ceiling. |
| `LOCAL_AI_CIRCUIT_FAILURE_THRESHOLD` | No | AI | No | `3` | Local-provider failures before circuit opens. |
| `LOCAL_AI_CIRCUIT_OPEN_SECONDS` | No | AI | No | `30` | Circuit-open duration. |
| `PARSER_TIMEOUT_SECONDS` | No | AI | No | `25` | Parser wall-clock budget. |
| `PARSER_CPU_SECONDS` | No | AI | No | `20` | Linux parser CPU budget. |
| `PARSER_MEMORY_MIB` | No | AI | No | `512` | Linux parser address-space budget. |
| `PARSER_STALE_WORK_SECONDS` | No | AI | No | `3600` | Age at which stale parser work is reconciled. |
| `GEMINI_API_KEY` | Conditional | AI | Yes | — | Gemini provider key. |
| `GEMINI_MODEL` | No | AI | No | `gemini-2.0-flash` | Gemini model. |
| `GROQ_API_KEY` | Conditional | AI | Yes | — | Groq provider key. |
| `GROQ_MODEL` | No | AI | No | `llama-3.3-70b-versatile` | Groq model. |
| `WORKER_AI_OPERATIONS_ENABLED` | No | API | No | `false` | Durable AI worker gate. |
| `AI_QUEUE_WORKER_CONCURRENCY` | No | API | No | `1` | AI worker concurrency. |
| `AI_QUEUE_GLOBAL_CAPACITY` | No | API | No | `100` | Global queued-operation capacity. |
| `AI_QUEUE_PER_USER_CAPACITY` | No | API | No | `10` | Per-user queued-operation capacity. |
| `AI_QUEUE_DEADLINE_MINUTES` | No | API | No | `15` | Queue deadline. |
| `AI_QUEUE_OPERATION_TIMEOUT_SECONDS` | No | API | No | `300` | Operation timeout. |
## Ingress, deployment, maintenance, and backups
| Variable | Required | Service | Secret | Default | Description |
|---|---|---|---|---|---|
| `WEB_PROXY_SUBNET` | Production | Compose | No | `172.31.250.0/29` | Dedicated nginx/backend network; verify no overlap. |
| `INGRESS_PROXY_CIDRS` | Production | Frontend | No | — | Trusted reverse-proxy socket peers. |
| `MAINTENANCE_GITEA_BASE_URL` | No | API | No | `https://git.cesnimda.uk` | Gitea API base for allowlisted maintenance jobs. |
| `MAINTENANCE_GITEA_OWNER` | No | API | No | `cesnimda` | Gitea owner. |
| `MAINTENANCE_GITEA_REPOSITORY` | No | API | No | `jobtrackingapp` | Gitea repository. |
| `MAINTENANCE_GITEA_TOKEN` | Conditional | API | Yes | — | Narrowly scoped workflow-dispatch token. |
| `BACKUP_TIMEZONE` | No | Ops | No | `Europe/Oslo` | Backup schedule timezone. |
| `BACKUP_DAILY_RETENTION_DAYS` | No | Ops | No | `30` | Daily recovery-set retention. |
| `BACKUP_MONTHLY_RETENTION_COUNT` | No | Ops | No | `12` | Monthly recovery-set count. |
| `BACKUP_RCLONE_REMOTE` | No | Ops | Yes/depends | — | Optional encrypted remote destination. |
## Email and workers
| Variable | Required | Service | Secret | Default | Description |
|---|---|---|---|---|---|
| `EMAIL_ENABLED` | No | API | No | `false` | Enables SMTP delivery. |
| `EMAIL_SMTP_HOST` | Conditional | API | No | `smtp.gmail.com` | SMTP host. |
| `EMAIL_SMTP_PORT` | Conditional | API | No | `587` | SMTP port. |
| `EMAIL_SMTP_USER` | Conditional | API | No | — | SMTP username. |
| `EMAIL_SMTP_PASSWORD` | Conditional | API | Yes | — | SMTP password/app password. |
| `EMAIL_FROM` | No | API | No | SMTP user | Sender address. |
| `EMAIL_FROM_NAME` | No | API | No | `Jobbjakt` | Sender display name. |
| `EMAIL_FOLLOWUPREMINDERS_ENABLED` | No | API | No | `false` | Reminder-email gate. |
| `EMAIL_FOLLOWUPREMINDERS_UPCOMINGDAYS` | No | API | No | `2` | Reminder look-ahead days. |
| `EMAIL_SMTP_ENABLE_SSL` | No | API | No | `true` | SMTP TLS setting. |
| `EMAIL_SMTP_TIMEOUT_MS` | No | API | No | `15000` | SMTP timeout. |
| `WORKER_RULES_ENABLED` | No | API | No | `false` | Rules/ghosting worker gate. |
| `WORKER_FOLLOWUP_REMINDERS_ENABLED` | No | API | No | `false` | Reminder worker gate. |
| `WORKER_SAVED_SEARCH_ALERTS_ENABLED` | No | API | No | `true` | Saved-search alert worker gate. |
| `SAVED_SEARCH_INTERVAL_HOURS` | No | API | No | `6` | Saved-search interval. |
| `WORKER_DAILY_EXPORT_ENABLED` | No | API | No | `false` | Daily export worker gate. |
| `WORKER_JOB_ENRICHMENT_ENABLED` | No | API | No | `false` | Job enrichment worker gate. |
## Runtime-only variables
The source also accepts `CV_FORCE_AI_NORMALIZER`, `CV_PDF_BROWSER_PATH`, `PARSER_TEMP_ROOT`, `GEMINI_BASE_URL`, `GROQ_BASE_URL`, `AI_SERVICE_SKIP_MODEL_LOAD`, and `AI_SERVICE_EAGER_MODEL_LOAD`. These are local/diagnostic/sidecar overrides and are intentionally not in the operator `.env.example`; see the relevant AI and testing guides. `GOOGLE_GMAIL_REDIRECT_URI` and `MICROSOFT_REDIRECT_URI` were present in the pre-cleanup local `.env` but have no current Compose/source consumer; they are retained locally for review and intentionally omitted from the template. `REACT_APP_API_BASE_URL` and `REACT_APP_GOOGLE_CLIENT_ID` are obsolete CRA names and must not be added back.
docs/configuration/environments.md
+13
View File
@@ -0,0 +1,13 @@
# Environments
## Local development
SQLite and localhost defaults are supported. Run the API on 5202 and the UI on 3000, or use the development Compose override. Use seeded development credentials only from local settings and never reuse them in production.
## Tests
Jest, Playwright, xUnit, and the Python tests create isolated fixtures or temporary databases. They may set test-only variables such as `AI_SERVICE_SKIP_MODEL_LOAD`; they must not use a real database, mailbox, provider key, or production URL.
## Production
Production requires an explicit database provider, authentication key/configuration, AI service token, public base URL, proxy CIDRs, and external secret storage. Leave `NEXT_PUBLIC_API_BASE_URL` empty so nginx provides same-origin `/api` unless an intentional external API origin is required.