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