Add a weekly digest and report which version of the agent each server runs

- Weekly digest through the notification channels: alerts now, a week of uptime, what happened, disks
  heading for full, expiring secrets and domains, updates waiting, planned maintenance. Off until switched
  on in Settings -> Notifications; Preview and Send it now there. Setting key 'digest'.
- Agents say their version in every report (Linux and Windows scripts are version 2); the server compares
  it with the scripts it serves and marks agents that are behind on the Servers, server and Updates pages.
  servers.agent_version, migration 0026.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
bobbanandClaude Sonnet 5.5 committed 2026-10-17 19:49:36 +02:00
1 parent 3da5c639b1
commit aa94d84f6c
28 files changed
+3179 -19

No files matched your search

+24 -2
View File
@@ -401,6 +401,15 @@ export interface QuietHoursSettings {
end: string;
}
/** The weekly digest: one message a week through the notification channels. */
export interface DigestSettings {
enabled: boolean;
/** 0 = Sunday … 6 = Saturday, in the notification time zone. */
day: number;
/** "HH:MM", in the notification time zone. */
time: string;
}
export interface AppSettings {
gotify: GotifySettings;
ntfy: NtfySettings;
@@ -413,6 +422,7 @@ export interface AppSettings {
logRetention: LogRetentionSettings;
quietHours: QuietHoursSettings;
healthChecks: HealthCheckSettings;
digest: DigestSettings;
}
export type AppSettingsPatch = { [K in keyof AppSettings]?: Partial<AppSettings[K]> };
@@ -496,6 +506,14 @@ export interface ServerRecord {
pendingUpdates: PendingUpdates | null;
/** When updates were first seen waiting (and none were before); null when none are. */
updatesPendingSince: string | null;
/** Which version of the agent script it runs, as the agent says; null from one that predates the number (version 1). */
agentVersion: number | null;
}
/** The agent version a new install would be, per system; null when this app can't tell. */
export interface AgentLatest {
linux: number | null;
windows: number | null;
}
export interface PendingUpdates {
@@ -515,6 +533,7 @@ export interface UpdatesServer {
lastSeenAt: string | null;
updates: PendingUpdates | null;
pendingSince: string | null;
agentVersion: number | null;
}
/** What a server runs on, and what runs on it. `auto`: worked out from the Proxmox node rather than set by hand. */
@@ -564,6 +583,7 @@ export interface ServerDetail {
dnsMatches: DnsMatch[];
links: ServerLink[];
relations: { parent: ServerRelation | null; children: ServerRelation[] };
agentLatest: AgentLatest;
}
export type AlertSeverity = "critical" | "warning" | "info";
@@ -1445,7 +1465,7 @@ export const api = {
clearCache: () => request<{ ok: true }>("/api/dns/cache/clear", { method: "POST" }),
},
servers: {
list: () => request<{ servers: ServerRecord[] }>("/api/servers"),
list: () => request<{ servers: ServerRecord[]; agentLatest: AgentLatest }>("/api/servers"),
create: (data: { name: string; hostname?: string; description?: string; osType?: "linux" | "windows" }) =>
request<{ server: ServerRecord; token: string }>("/api/servers", {
method: "POST",
@@ -1458,7 +1478,7 @@ export const api = {
update: (id: number, data: ServerUpdateInput) =>
request<{ server: ServerRecord }>(`/api/servers/${id}`, { method: "PATCH", body: JSON.stringify(data) }),
summary: () => request<ServerSummary>("/api/servers/summary"),
updates: () => request<{ servers: UpdatesServer[] }>("/api/servers/updates"),
updates: () => request<{ servers: UpdatesServer[]; agentLatest: AgentLatest }>("/api/servers/updates"),
detail: (id: number) => request<ServerDetail>(`/api/servers/${id}/detail`),
activity: (id: number) => request<{ events: ServerActivityEvent[] }>(`/api/servers/${id}/activity`),
metrics: (id: number, days: number) => request<{ days: number; series: ServerMetricSeries[] }>(`/api/servers/${id}/metrics?days=${days}`),
@@ -1677,5 +1697,7 @@ export const api = {
"/api/settings/quiet-hours-queue",
),
flushQuietHours: () => request<{ flushed: number }>("/api/settings/flush-quiet-hours", { method: "POST" }),
digestPreview: () => request<{ title: string; message: string; quiet: boolean; channels: number }>("/api/settings/digest/preview"),
digestSend: () => request<{ sent: boolean; channels: number }>("/api/settings/digest/send", { method: "POST" }),
},
};
+12
View File
@@ -20,6 +20,7 @@ import UptimeRibbon from "../components/UptimeRibbon";
import RunsOn from "../components/RunsOn";
import RunPlaybook from "../components/RunPlaybook";
import UpdatesBadge from "../components/UpdatesBadge";
import { agentState, agentVersionWords } from "../utils/agent";
import ServerTags from "../components/ServerTags";
import ServerTaskTable, { SCHEDULE_TYPE_LABELS } from "../components/ServerTaskTable";
import { formatDateTime } from "../utils/date";
@@ -777,6 +778,17 @@ export default function ServerDetail({ user }: { user: CurrentUser }) {
)}
{server.lastSeenAt && (
<>
<dt className="col-5">Agent</dt>
<dd className="col-7">
{agentVersionWords(server.agentVersion)}{" "}
{agentState(server, detail.agentLatest) === "behind" ? (
<span className="badge bg-yellow-lt text-yellow" title="Run its install command again to update it (Servers → Manage servers).">
update available
</span>
) : (
<span className="badge bg-green-lt text-green">current</span>
)}
</dd>
<dt className="col-5">Updates</dt>
<dd className="col-7">
<UpdatesBadge updates={server.pendingUpdates} />
+19 -3
View File
@@ -1,6 +1,6 @@
import { useCallback, useEffect, useState, type CSSProperties } from "react";
import { Link, useSearchParams } from "react-router-dom";
import { api, type CurrentUser, type ServerRecord } from "../api/client";
import { api, type AgentLatest, type CurrentUser, type ServerRecord } from "../api/client";
import CopyButton from "../components/CopyButton";
import { formatDateTime } from "../utils/date";
import TimeAgo from "../components/TimeAgo";
@@ -19,6 +19,7 @@ import { toast } from "../utils/toast";
import { SearchBox } from "../components/TableToolbar";
import { useTableSearch } from "../hooks/useTableSearch";
import SaveViewButton from "../components/SaveViewButton";
import { agentState } from "../utils/agent";
function typeBadgeStyle(colors: Record<string, string>, type: string): CSSProperties {
const color = colors[type];
@@ -31,6 +32,7 @@ export default function Servers({ user }: { user: CurrentUser }) {
const isAdmin = user.role === "admin";
const [servers, setServers] = useState<ServerRecord[]>([]);
const [agentLatest, setAgentLatest] = useState<AgentLatest | null>(null);
const [error, setError] = useState<string | null>(null);
const [managingServers, setManagingServers] = useState(false);
const [integrationColors, setIntegrationColors] = useState<Record<string, string>>({});
@@ -68,7 +70,10 @@ export default function Servers({ user }: { user: CurrentUser }) {
const loadServers = useCallback(() => {
return api.servers
.list()
.then((res) => setServers(res.servers))
.then((res) => {
setServers(res.servers);
setAgentLatest(res.agentLatest);
})
.catch((err) => setError(String(err)));
}, []);
@@ -184,7 +189,13 @@ export default function Servers({ user }: { user: CurrentUser }) {
Proxmox
</span>
) : s.lastSeenAt ? (
<span className="badge bg-green-lt text-green">Agent</span>
agentState(s, agentLatest) === "behind" ? (
<span className="badge bg-yellow-lt text-yellow" title="Its agent is older than the one this Homelab Manager would install now. Run its install command again to update it.">
Agent behind
</span>
) : (
<span className="badge bg-green-lt text-green">Agent</span>
)
) : (
<span className="badge bg-secondary-lt text-secondary">No data</span>
)}
@@ -385,6 +396,11 @@ export default function Servers({ user }: { user: CurrentUser }) {
<tr key={s.id}>
<td>
<Link to={`/servers/${s.id}`}>{s.name}</Link>
{agentState(s, agentLatest) === "behind" && (
<span className="badge bg-yellow-lt text-yellow ms-2" title="Its agent is older than the one this Homelab Manager would install now. Run its install command again to update it.">
agent behind
</span>
)}
</td>
<td>{s.hostname ?? "—"}</td>
<td>
+24 -5
View File
@@ -1,6 +1,7 @@
import { useEffect, useState } from "react";
import { Link } from "react-router-dom";
import { api, type DockhandContainer, type UpdatesServer } from "../api/client";
import { api, type AgentLatest, type DockhandContainer, type UpdatesServer } from "../api/client";
import { agentState, agentVersionWords } from "../utils/agent";
import SortableTh from "../components/SortableTh";
import TableToolbar from "../components/TableToolbar";
import TimeAgo from "../components/TimeAgo";
@@ -24,6 +25,7 @@ interface Row {
/** ISO — when updates were first seen waiting. */
since: string | null;
reportedAt: string | null;
agentVersion: number | null;
server: UpdatesServer;
}
@@ -38,6 +40,7 @@ function toRow(s: UpdatesServer): Row {
restart: s.updates?.rebootRequired ?? false,
since: s.pendingSince,
reportedAt: s.updates?.reportedAt || null,
agentVersion: s.agentVersion,
server: s,
};
}
@@ -51,6 +54,7 @@ const DAY_MS = 86_400_000;
*/
export default function Updates() {
const [servers, setServers] = useState<UpdatesServer[] | null>(null);
const [agentLatest, setAgentLatest] = useState<AgentLatest | null>(null);
const [containers, setContainers] = useState<(DockhandContainer & { integrationName: string })[] | null>(null);
const [error, setError] = useState<string | null>(null);
const [onlyWaiting, setOnlyWaiting] = useState(false);
@@ -59,7 +63,11 @@ export default function Updates() {
let alive = true;
api.servers
.updates()
.then((res) => alive && setServers(res.servers))
.then((res) => {
if (!alive) return;
setServers(res.servers);
setAgentLatest(res.agentLatest);
})
.catch((err) => alive && setError(readableError(err)));
api.integrations
.list()
@@ -91,6 +99,7 @@ export default function Updates() {
const restarts = rows.filter((r) => r.restart).length;
const oldest = waiting.map((r) => r.since).filter((s): s is string => !!s).sort()[0];
const notReporting = rows.length - reporting;
const behind = rows.filter((r) => agentState(r.server, agentLatest) === "behind").length;
function exportCsv() {
if (!sorted) return;
@@ -105,6 +114,7 @@ export default function Updates() {
{ label: "Servers with updates waiting", value: servers ? `${waiting.length} of ${reporting}` : "…", note: notReporting > 0 ? `${notReporting} haven't reported updates` : undefined, color: waiting.length > 0 ? "text-yellow" : "text-green" },
{ label: "Security updates waiting", value: servers ? securityTotal : "…", color: securityTotal > 0 ? "text-red" : "text-green" },
{ label: "Need a restart", value: servers ? restarts : "…", color: restarts > 0 ? "text-orange" : "text-green" },
{ label: "Agents to update", value: servers ? behind : "…", note: behind > 0 ? "run their install command again" : undefined, color: behind > 0 ? "text-yellow" : "text-green" },
{ label: "Longest wait", value: oldest ? `${Math.max(1, Math.floor((Date.now() - Date.parse(oldest)) / DAY_MS))} d` : servers ? "—" : "…", color: "text-secondary" },
];
@@ -120,7 +130,7 @@ export default function Updates() {
<div className="row row-cards mb-3">
{cards.map((c) => (
<div className="col-6 col-lg-3" key={c.label}>
<div className="col-6 col-lg" key={c.label}>
<div className="card card-sm">
<div className="card-body">
<div className={`h2 mb-0 ${c.color}`}>{c.value}</div>
@@ -157,12 +167,13 @@ export default function Updates() {
<SortableTh<Row> label="Security" sortKeyName="security" activeKey={sortKey} direction={sortDir} onSort={requestSort} />
<SortableTh<Row> label="Waiting since" sortKeyName="since" activeKey={sortKey} direction={sortDir} onSort={requestSort} />
<SortableTh<Row> label="Reported" sortKeyName="reportedAt" activeKey={sortKey} direction={sortDir} onSort={requestSort} />
<SortableTh<Row> label="Agent" sortKeyName="agentVersion" activeKey={sortKey} direction={sortDir} onSort={requestSort} />
</tr>
</thead>
<tbody>
{servers === null && !error && (
<tr>
<td colSpan={5}>
<td colSpan={6}>
<BlockSkeleton lines={3} />
</td>
</tr>
@@ -178,11 +189,19 @@ export default function Updates() {
<td>{r.security === null ? <span className="text-secondary">—</span> : r.security}</td>
<td className="text-secondary">{r.since ? <TimeAgo value={r.since} /> : "—"}</td>
<td className="text-secondary">{r.reportedAt ? <TimeAgo value={r.reportedAt} /> : "—"}</td>
<td>
{agentVersionWords(r.agentVersion)}{" "}
{agentState(r.server, agentLatest) === "behind" && (
<span className="badge bg-yellow-lt text-yellow" title="Older than the agent this Homelab Manager would install now.">
behind
</span>
)}
</td>
</tr>
))}
{servers !== null && sorted?.length === 0 && (
<tr>
<td colSpan={5} className="text-secondary text-center">
<td colSpan={6} className="text-secondary text-center">
{tableSearch.active || onlyWaiting ? "Nothing matches that." : "No server has reported yet."}
</td>
</tr>
+102 -1
View File
@@ -7,9 +7,11 @@ import {
type SmtpSettings,
type WebhookSettings,
type NotificationEvents,
type DigestSettings,
type QuietHoursSettings,
type HealthCheckSettings,
} from "../../api/client";
import { readableError } from "../../utils/errors";
import { ErrorNotice } from "../../components/Notice";
import { PageSkeleton } from "../../components/Skeleton";
@@ -58,6 +60,17 @@ const DEFAULT_NOTIFICATIONS: NotificationEvents = {
integrationFailureThreshold: 3,
};
const DEFAULT_QUIET_HOURS: QuietHoursSettings = { enabled: false, start: "22:00", end: "07:00" };
const DEFAULT_DIGEST: DigestSettings = { enabled: false, day: 1, time: "08:00" };
// Monday first, as a week reads; the numbers are what the server keeps (0 = Sunday).
const DIGEST_DAYS: { value: number; label: string }[] = [
{ value: 1, label: "Monday" },
{ value: 2, label: "Tuesday" },
{ value: 3, label: "Wednesday" },
{ value: 4, label: "Thursday" },
{ value: 5, label: "Friday" },
{ value: 6, label: "Saturday" },
{ value: 0, label: "Sunday" },
];
const DEFAULT_HEALTH_CHECKS: HealthCheckSettings = { serverOfflineMinutes: 60, diskUsagePercent: 90, domainWarnDays: 30, diskForecastDays: 14 };
type TestResult = { ok: boolean; message: string } | null;
@@ -85,6 +98,10 @@ export default function NotificationSettings() {
const [notifications, setNotifications] = useState<NotificationEvents>(DEFAULT_NOTIFICATIONS);
const [quietHours, setQuietHours] = useState<QuietHoursSettings>(DEFAULT_QUIET_HOURS);
const [healthChecks, setHealthChecks] = useState<HealthCheckSettings>(DEFAULT_HEALTH_CHECKS);
const [digest, setDigest] = useState<DigestSettings>(DEFAULT_DIGEST);
const [digestPreview, setDigestPreview] = useState<{ title: string; message: string } | null>(null);
const [digestBusy, setDigestBusy] = useState<"preview" | "send" | null>(null);
const [digestResult, setDigestResult] = useState<TestResult>(null);
const [queuedCount, setQueuedCount] = useState<number | null>(null);
const [flushing, setFlushing] = useState(false);
const [flushResult, setFlushResult] = useState<string | null>(null);
@@ -109,6 +126,7 @@ export default function NotificationSettings() {
setNotifications(res.settings.notifications);
setQuietHours(res.settings.quietHours);
setHealthChecks(res.settings.healthChecks);
setDigest(res.settings.digest ?? DEFAULT_DIGEST);
})
.catch((err) => setLoadError(err instanceof Error ? err.message : String(err)))
.finally(() => setLoading(false));
@@ -123,7 +141,7 @@ export default function NotificationSettings() {
setSaveError(null);
setSaved(false);
try {
await api.settings.update({ gotify, ntfy, smtp, webhook, notifications, quietHours, healthChecks });
await api.settings.update({ gotify, ntfy, smtp, webhook, notifications, quietHours, healthChecks, digest });
setSaved(true);
setTimeout(() => setSaved(false), 3000);
} catch (err) {
@@ -133,6 +151,32 @@ export default function NotificationSettings() {
}
}
async function handleDigestPreview() {
setDigestBusy("preview");
setDigestResult(null);
try {
const res = await api.settings.digestPreview();
setDigestPreview({ title: res.title, message: res.message });
} catch (err) {
setDigestResult({ ok: false, message: err instanceof Error ? err.message : String(err) });
} finally {
setDigestBusy(null);
}
}
async function handleDigestSend() {
setDigestBusy("send");
setDigestResult(null);
try {
const res = await api.settings.digestSend();
setDigestResult({ ok: true, message: `Sent through ${res.channels} channel${res.channels === 1 ? "" : "s"}.` });
} catch (err) {
setDigestResult({ ok: false, message: readableError(err) });
} finally {
setDigestBusy(null);
}
}
async function handleFlushNow() {
setFlushing(true);
setFlushResult(null);
@@ -740,6 +784,63 @@ export default function NotificationSettings() {
</div>
</div>
</div>
<div className="col-md-6">
<div className="card">
<div className="card-header">
<h3 className="card-title">Weekly digest</h3>
</div>
<div className="card-body">
<p className="text-secondary">
One message a week through the channels above, in the time zone set above: what is wrong now, what was down and for how long, what happened,
disks heading for full, things about to expire, updates waiting and maintenance coming up. A topic with nothing to say is left out, and a
quiet week says so in one line. Quiet hours hold it like any other notification.
</p>
<label className="form-check mb-3">
<input type="checkbox" className="form-check-input" checked={digest.enabled} onChange={(e) => setDigest((d) => ({ ...d, enabled: e.target.checked }))} />
<span className="form-check-label">Send the weekly digest</span>
</label>
<div className="row g-2 mb-3">
<div className="col-6">
<label className="form-label" htmlFor="digest-day">
Day
</label>
<select id="digest-day" className="form-select" value={digest.day} disabled={!digest.enabled} onChange={(e) => setDigest((d) => ({ ...d, day: Number(e.target.value) }))}>
{DIGEST_DAYS.map((d) => (
<option key={d.value} value={d.value}>
{d.label}
</option>
))}
</select>
</div>
<div className="col-6">
<label className="form-label" htmlFor="digest-time">
Time
</label>
<input id="digest-time" type="time" className="form-control" value={digest.time} disabled={!digest.enabled} onChange={(e) => setDigest((d) => ({ ...d, time: e.target.value }))} />
</div>
</div>
<div className="btn-list">
<button type="button" className="btn btn-outline-secondary" onClick={handleDigestPreview} disabled={digestBusy !== null}>
{digestBusy === "preview" ? "Gathering…" : "Preview"}
</button>
<button type="button" className="btn btn-outline-secondary" onClick={handleDigestSend} disabled={digestBusy !== null}>
{digestBusy === "send" ? "Sending…" : "Send it now"}
</button>
</div>
<div className="form-hint mt-2">Settings above are saved with the Save button; the preview and "send it now" don't depend on them.</div>
<TestBadge result={digestResult} />
{digestPreview && (
<div className="mt-3">
<div className="fw-bold">{digestPreview.title}</div>
<pre className="border rounded p-2 mt-1 mb-0" style={{ whiteSpace: "pre-wrap", fontSize: "0.8125rem" }}>
{digestPreview.message}
</pre>
</div>
)}
</div>
</div>
</div>
</div>
</>
);
+20
View File
@@ -0,0 +1,20 @@
import type { AgentLatest } from "../api/client";
/** What an agent's version means for a server, for the badges: not on an agent at all, current, or behind. */
export type AgentState = "none" | "current" | "behind";
/**
* Whether a server's agent is behind what this Homelab Manager would install today. The same rule the server uses: only a server that
* reports through an agent has one, and an agent that says no version is version 1.
*/
export function agentState(server: { osType: string; lastSeenAt: string | null; agentVersion: number | null }, latest: AgentLatest | null): AgentState {
if (!server.lastSeenAt) return "none";
const newest = latest ? (server.osType === "windows" ? latest.windows : server.osType === "linux" ? latest.linux : null) : null;
if (newest === null || newest === undefined) return "current"; // nothing to compare with: don't cry wolf
return (server.agentVersion ?? 1) < newest ? "behind" : "current";
}
/** "v2", or "v1 or older" for one that has never said. */
export function agentVersionWords(version: number | null): string {
return version === null ? "v1 or older" : `v${version}`;
}