91 lines
3.4 KiB
Markdown
91 lines
3.4 KiB
Markdown
# 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.
|