docs: cut version 0.1.26

2026-02-20 18:24:16 +00:00
parent 483e5f49e0
commit 89ff770416
31 changed files with 2829 additions and 1 deletions
@@ -0,0 +1,127 @@
+---
+id: database-backups
+title: Database Backups
+description: Configure, run, and restore JobOps database backups.
+sidebar_position: 2
+---
+
+## What this covers
+
+This page is about database backups:
+
+- automatic backup schedule
+- manual backup creation/deletion
+- retention behavior
+- restore workflow
+- backup troubleshooting
+
+## Backup behavior
+
+JobOps stores backups in the same data directory as `jobs.db`.
+
+Two backup types exist:
+
+- **Automatic** backups
+- **Manual** backups
+
+### Automatic backups
+
+- Scheduled daily.
+- Filename format: `jobs_YYYY_MM_DD.db`
+- Schedule hour is configured in Settings (**UTC hour**).
+- Automatic retention is capped by `backupMaxCount`.
+- If today’s automatic backup already exists, JobOps skips creating a duplicate.
+
+### Manual backups
+
+- Triggered from Settings or `POST /api/backups`.
+- Filename format: `jobs_manual_YYYY_MM_DD_HH_MM_SS.db`
+- If a filename collision occurs, JobOps appends `_1`, `_2`, etc.
+- Manual backups are **not** auto-deleted by automatic retention cleanup.
+
+## Configure backups
+
+In **Settings → Backup**:
+
+1. Enable automatic backups.
+2. Set backup hour (`0-23`, UTC).
+3. Set max automatic backups to keep (`1-5`).
+4. Save settings.
+
+## API reference
+
+```bash
+# List backups + next scheduled run time
+curl "http://localhost:3001/api/backups"
+```
+
+```bash
+# Create a manual backup
+curl -X POST "http://localhost:3001/api/backups"
+```
+
+```bash
+# Delete a specific backup
+curl -X DELETE "http://localhost:3001/api/backups/jobs_manual_2026_02_15_10_20_30.db"
+```
+
+```bash
+# Update backup settings via Settings API
+curl -X PATCH "http://localhost:3001/api/settings" \
+  -H "content-type: application/json" \
+  -d '{
+    "backupEnabled": true,
+    "backupHour": 2,
+    "backupMaxCount": 5
+  }'
+```
+
+## Restore workflow
+
+To restore from a backup:
+
+1. Stop JobOps.
+2. Locate backup files in your data directory.
+3. Copy the chosen backup over the main DB file (`jobs.db`).
+4. Start JobOps.
+5. Verify jobs/runs in the UI.
+
+Example shell flow:
+
+```bash
+# Example only: adjust paths for your setup
+cp /path/to/data/jobs_manual_2026_02_15_10_20_30.db /path/to/data/jobs.db
+```
+
+## Troubleshooting
+
+### Backups are not running automatically
+
+- Confirm `backupEnabled` is true.
+- Confirm backup hour is set as intended (UTC, not local time).
+- Verify the app process is running at scheduled time.
+
+### `POST /api/backups` fails
+
+- Confirm the data directory and `jobs.db` are writable/readable.
+- Confirm `jobs.db` exists.
+- In demo mode, manual backup creation is blocked.
+
+### Cannot delete a backup
+
+- Filename must match valid backup patterns.
+- Invalid names and missing files return errors.
+
+### Next scheduled time is null
+
+- Automatic backups are currently disabled.
+
+## Notes
+
+- Backup cleanup applies only to automatic backups.
+- Manual backups stay until you delete them.
+
+## Related pages
+
+- [Settings](../features/settings)
+- [Self-Hosting](./self-hosting)
@@ -0,0 +1,96 @@
+---
+id: gmail-oauth-setup
+title: Gmail OAuth Setup
+description: Step-by-step Google Cloud setup for JobOps Gmail tracking, with exact scopes and callback configuration.
+sidebar_position: 2
+---
+
+## What it is
+
+This guide configures Google OAuth so JobOps can read recruitment emails from Gmail for the Tracking Inbox.
+
+## Why it exists
+
+Gmail OAuth setup is easy to misconfigure (wrong redirect URI, missing refresh token, or unnecessary scopes). This page documents the exact defaults JobOps expects.
+
+## How to use it
+
+### 1) Create Google Cloud credentials
+
+In [Google Cloud Console](https://console.cloud.google.com/):
+
+1. Create (or select) a project.
+2. Open **APIs & Services → Library** and enable **Gmail API**.
+3. Open **APIs & Services → OAuth consent screen** and configure your app.
+4. Open **APIs & Services → Credentials** and create **OAuth client ID**.
+5. Choose **Web application**.
+6. Add at least one authorized redirect URI:
+  - Local: `http://localhost:3005/oauth/gmail/callback`
+  - Production: `https://your-domain.com/oauth/gmail/callback`
+
+Notes:
+
+- If you set `GMAIL_OAUTH_REDIRECT_URI`, it must exactly match a redirect URI in Google Cloud.
+- JobOps does not require JavaScript origins for this flow.
+
+### 2) Set environment variables
+
+Configure:
+
+```bash
+GMAIL_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
+GMAIL_OAUTH_CLIENT_SECRET=your-client-secret
+# Optional (recommended in production)
+GMAIL_OAUTH_REDIRECT_URI=https://your-domain.com/oauth/gmail/callback
+```
+
+Then restart the container/app.
+
+### 3) Connect Gmail in JobOps
+
+1. Open **Tracking Inbox**.
+2. Click **Connect Gmail**.
+3. Complete Google consent.
+
+JobOps starts OAuth with:
+
+- Scope: `https://www.googleapis.com/auth/gmail.readonly`
+- `access_type=offline` (requests refresh token)
+- `prompt=consent` (forces consent screen so refresh token is returned reliably)
+
+### 4) Scope reference (required vs not required)
+
+Required by JobOps:
+
+- `https://www.googleapis.com/auth/gmail.readonly`
+
+Not required for JobOps Gmail ingestion:
+
+- `https://www.googleapis.com/auth/gmail.modify`
+- `openid`
+- `https://www.googleapis.com/auth/userinfo.email`
+- `https://www.googleapis.com/auth/userinfo.profile`
+
+## Common problems
+
+### Redirect URI mismatch
+
+- Symptom: Google returns `redirect_uri_mismatch`.
+- Fix: ensure the exact callback URL in `GMAIL_OAUTH_REDIRECT_URI` is also present in the OAuth client redirect URIs.
+
+### No refresh token returned
+
+- Symptom: connect fails after OAuth exchange.
+- Fix: remove app access in your Google account, then reconnect so consent is re-granted.
+
+### Gmail connects but no inbox results
+
+- Check that your account actually has recruitment/application emails.
+- Trigger a sync and increase `searchDays` if needed.
+
+## Related pages
+
+- [Self-Hosting (Docker Compose)](/docs/next/getting-started/self-hosting)
+- [Post-Application Tracking](/docs/next/features/post-application-tracking)
+- [Post-Application Workflow](/docs/next/workflows/post-application-workflow)
+- [Common Problems](/docs/next/troubleshooting/common-problems)
@@ -0,0 +1,126 @@
+---
+id: self-hosting
+title: Self-Hosting (Docker Compose)
+description: Deploy JobOps with Docker Compose and configure onboarding integrations.
+sidebar_position: 1
+---
+
+The easiest way to run JobOps is via Docker Compose. The app is self-configuring and guides you through setup on first launch.
+
+## Prerequisites
+
+- Docker Desktop or Docker Engine + Compose v2
+
+## 1) Start the stack
+
+No environment variables are required to boot:
+
+```bash
+docker compose up -d
+```
+
+This pulls the pre-built image from GHCR and starts the API, UI, and scrapers in one container.
+
+To build locally instead:
+
+```bash
+docker compose up -d --build
+```
+
+## 2) Access the app and onboard
+
+Open:
+
+- **Dashboard**: `http://localhost:3005`
+
+The onboarding wizard helps you validate and save:
+
+1. **LLM Provider**: OpenRouter by default (or OpenAI/Gemini/local URL).
+2. **PDF Export**: RxResume credentials for PDF generation.
+3. **Template Resume**: Choose a base resume from your RxResume account.
+
+Settings are saved to the local database.
+
+## Gmail OAuth (Tracking Inbox)
+
+If you want Gmail integration, configure OAuth credentials.
+
+### 1) Create Google OAuth credentials
+
+In Google Cloud:
+
+1. Configure OAuth consent screen.
+2. Enable Gmail API.
+3. Create OAuth client ID (`Web application`).
+4. Add redirect URI:
+  - `http://localhost:3005/oauth/gmail/callback`
+  - Or your production URL, for example `https://your-domain.com/oauth/gmail/callback`
+
+### 2) Configure environment variables
+
+- `GMAIL_OAUTH_CLIENT_ID` (required)
+- `GMAIL_OAUTH_CLIENT_SECRET` (required)
+- `GMAIL_OAUTH_REDIRECT_URI` (optional, recommended in production)
+
+### 3) Restart and connect
+
+- Restart container
+- Open Tracking Inbox and click **Connect Gmail**
+
+For a full step-by-step setup, exact scope requirements, and troubleshooting, see:
+
+- [Gmail OAuth Setup](/docs/next/getting-started/gmail-oauth-setup)
+
+## Email-to-job matching overview
+
+```mermaid
+flowchart TD
+    A[Recruitment email arrives in Gmail] --> B[Smart Router AI analyzes content]
+    B --> C{How confident is the match?}
+
+    C -->|95-100%| D[Auto-linked to job]
+    D --> E[Timeline updated automatically]
+
+    C -->|50-94%| F[Goes to Inbox for review with suggested job match]
+
+    C -->|<50%| G{Is it relevant?}
+    G -->|Yes| H[Goes to Inbox as orphan]
+    G -->|No| I[Ignored]
+
+    F --> J{User review}
+    H --> J
+    J -->|Approve| K[Linked to job + timeline update]
+    J -->|Ignore| L[Marked not relevant]
+```
+
+## Persistent data
+
+`./data` bind-mount stores:
+
+- SQLite DB: `data/jobs.db`
+- Generated PDFs: `data/pdfs/`
+
+## Public demo mode
+
+Set `DEMO_MODE=true` for sandbox deployments.
+
+Behavior in demo mode:
+
+- Works locally: browsing/filtering/status/timeline edits
+- Simulated: pipeline run/summarize/process/rescore/pdf/apply
+- Blocked: settings writes, DB clear, backups
+- Auto-reset: every 6 hours
+
+## Updating
+
+```bash
+git pull
+docker compose pull
+docker compose up -d
+```
+
+## Self-hosted Reactive Resume
+
+If you self-host Reactive Resume, set:
+
+- `RXRESUME_URL=http://rxresume.local.net`