first commit

2026-07-09 22:51:03 +02:00
commit fac491134d
50 changed files with 7547 additions and 0 deletions
@@ -0,0 +1,90 @@
+# Schedule Task Manager
+
+Tracks scheduled tasks (cron jobs, systemd timers) across your homelab servers,
+grouped by server and schedule type. Servers push their task list to this app
+via a small agent script; sign-in is delegated to Authentik (OIDC).
+
+v1 scope: Linux servers only (cron + systemd timers). Windows Task Scheduler
+support is a documented future addition — see [`agent/windows/README.md`](agent/windows/README.md).
+
+## Architecture
+
+- `server/` — Express + TypeScript API, SQLite (via libSQL) storage, Authentik OIDC login.
+- `web/` — React + Vite single-page app, served as static files by the Express server.
+- `agent/linux/` — `report-tasks.sh` (collects cron + systemd timer data) and
+  `install.sh` (installs it as a systemd timer on a target server).
+
+Data model, API contract, and sync behavior are documented in code:
+[`server/src/db/schema.ts`](server/src/db/schema.ts),
+[`server/src/routes/agentReport.ts`](server/src/routes/agentReport.ts),
+[`server/src/services/taskSync.ts`](server/src/services/taskSync.ts).
+
+## 1. Set up an Authentik application
+
+In Authentik:
+
+1. Create an **OAuth2/OpenID Provider**:
+   - Redirect URI: `<APP_BASE_URL>/auth/callback` (e.g. `https://schedule.example.lan/auth/callback`)
+   - Scopes: `openid`, `email`, `profile`
+2. Create an **Application** using that provider, and assign the users/groups who
+   should be allowed to sign in — Authentik controls who can authenticate; the
+   app itself has no separate user list.
+3. Copy the provider's issuer URL, client ID, and client secret into `.env`
+   (see `.env.example`).
+
+## 2. Run with Docker (recommended)
+
+```sh
+cp .env.example .env
+# edit .env: APP_BASE_URL, SESSION_SECRET, AUTHENTIK_*
+
+docker compose up -d --build
+```
+
+The app listens on `HOST_PORT` (default `3000`). SQLite data and session
+files persist in `./data` on the host.
+
+## 3. Local development
+
+Requires Node.js 20+.
+
+```sh
+npm install
+cp .env.example .env   # fill in AUTHENTIK_* to test real login, or leave
+                        # blank to run everything except /auth/login locally
+
+npm run dev:server   # http://localhost:3000 (API)
+npm run dev:web      # http://localhost:5173 (Vite dev server, proxies /api and /auth to :3000)
+```
+
+Visit `http://localhost:5173` during development. Database migrations run
+automatically on server start.
+
+## 4. Add a server and install the agent
+
+1. Sign in, go to **Servers**, and add a server. The generated API token is
+   shown once — copy it.
+2. On the target Linux server (as root):
+
+   ```sh
+   curl -fsSL https://schedule.example.lan/agent/linux/install.sh | \
+     API_URL=https://schedule.example.lan API_TOKEN=stm_xxx bash
+   ```
+
+   This installs `report-tasks.sh` to `/usr/local/bin`, writes the API
+   credentials to `/etc/schedule-task-manager-agent.env`, and installs a
+   `schedule-task-manager-agent.timer` systemd timer that reports every 15
+   minutes (override with `INTERVAL_MINUTES=5` before the `bash` above).
+
+   Requires `curl`, `jq`, and `systemd` on the target server.
+
+3. Tasks appear on the Dashboard, grouped by server and then by schedule type,
+   within one reporting interval.
+
+Tasks that stop appearing in a server's report are marked **stale** rather
+than deleted (so a temporary agent failure doesn't wipe history) and are
+hidden by default — toggle "Show stale/missing tasks" to see them.
+
+## Environment variables
+
+See [`.env.example`](.env.example) for the full list with descriptions.