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) 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/routes/agentReport.ts, server/src/services/taskSync.ts.

1. Set up an Authentik application

In Authentik:

Create an OAuth2/OpenID Provider:
- Redirect URI: <APP_BASE_URL>/auth/callback (e.g. https://schedule.example.lan/auth/callback)
- Scopes: openid, email, profile
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.
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

Sign in, go to Servers, and add a server. The generated API token is shown once — copy it.
On the target Linux server (as root):
```
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.
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 for the full list with descriptions.

3.4 KiB Raw Permalink Blame History