bobban
329dcab936
curl ... | API_URL=... bash runs as the invoking user, not root, so "sudo" has to go right after the pipe (elevating bash) rather than before curl — the old commands in the app UI, README, and scripts' own usage comments put it in a spot that still failed the root check. Also have install.sh/report-tasks.sh suggest the right package-manager command (apt/dnf/yum/apk/pacman/zypper) when curl or jq is missing instead of just failing, and bring the README up to date with both.
117 lines
4.6 KiB
Markdown
117 lines
4.6 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),
|
|
`install.sh` (installs it as a systemd timer on a target server), and
|
|
`uninstall.sh` (removes it).
|
|
|
|
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. If you're not already root, put
|
|
`sudo` right after the pipe so it elevates `bash`, not `curl` — `sudo curl
|
|
... | bash` would still fail the root check:
|
|
|
|
```sh
|
|
curl -fsSL https://schedule.example.lan/agent/linux/install.sh | \
|
|
sudo 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 — if either
|
|
`curl` or `jq` is missing, both this script and `report-tasks.sh` print
|
|
the right install command for the server's package manager (apt, dnf,
|
|
yum, apk, pacman, or zypper) and exit.
|
|
|
|
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 | sudo 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.
|