ScheduleTaskManager/README.md

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.

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/routes/agentReport.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)

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+.

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:

   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:

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 for the full list with descriptions.