bobban
0615866311
Lets a server be cleanly removed from agent management: uninstall.sh stops/disables the systemd timer and deletes the unit files, the installed script, and the credentials env file, without touching the server's entry or task history in the app. install.sh now prints the uninstall command on success, and the Servers page has an "Uninstall" button that reveals the same command (safe to show anytime since it carries no secret).
111 lines
4.2 KiB
Markdown
111 lines
4.2 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.
|
|
|
|
To remove the agent from a server, run:
|
|
|
|
```sh
|
|
curl -fsSL https://schedule.example.lan/agent/linux/uninstall.sh | bash
|
|
```
|
|
|
|
This stops and deletes the systemd timer/service, the installed script, and
|
|
`/etc/schedule-task-manager-agent.env` (which holds the API token). It does
|
|
not delete the server's entry or task history in the app — the same "Uninstall"
|
|
button on the Servers page shows this command, and "Delete" removes the entry
|
|
entirely if you no longer want it tracked.
|
|
|
|
## 5. Manually tracked tasks
|
|
|
|
Not everything is discoverable by the agent — e.g. a scheduled job running
|
|
inside a Docker container. Use **Add task** on the Dashboard to log those by
|
|
hand. Manually entered tasks are never touched by agent reports (they have
|
|
their own `origin`), so they won't be marked stale or overwritten by the next
|
|
sync.
|
|
|
|
## Environment variables
|
|
|
|
See [`.env.example`](.env.example) for the full list with descriptions.
|