- Share links can open a status page: an admin picks servers, integrations and Uptime Kuma monitors and names them; the public sees only those names, Working / Not working / Being worked on / Can't tell, an optional message and the 30-day figure (share_links.kind/ title/message and status_items, migration 0033). A status address doesn't open the wall and the other way round; Uptime Kuma is asked at most every 30 seconds - Grafana dashboard built from code (download in Settings -> API and webhooks); a test checks it only uses series /metrics serves - Tests and docs Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
792 lines
54 KiB
Markdown
792 lines
54 KiB
Markdown
# Homelab Manager
|
||
|
||
Repository: `git@10.200.5.13:bobban/Homelab-manager.git` ([gitea.labsconnect.se/bobban/Homelab-manager](https://gitea.labsconnect.se/bobban/Homelab-manager) externally).
|
||
|
||
A single dashboard for a homelab: Proxmox, Synology DSM, Semaphore, Tailscale,
|
||
Gitea, Dockhand/Docker, Uptime Kuma, Proxmox Backup Server, and osTicket status
|
||
and basic actions, plus DNS record
|
||
management, an IP address inventory (IPAM), and a secret-expiry tracker
|
||
(ported from [Sloth Manager](../Sloth%20manager)) and scheduled-task tracking
|
||
across Debian/Raspbian hosts (ported from
|
||
[Schedule Task Manager](../ScheduleTaskManager)). Looks and feels like a
|
||
[Tabler](https://tabler.io) admin dashboard. Sign-in is delegated to
|
||
Authentik (OIDC), with local admin/operator/viewer roles.
|
||
|
||
## Status
|
||
|
||
All modules from the original plan are built:
|
||
|
||
- Monorepo scaffold, Tabler-themed app shell with a grouped sidebar (Infrastructure, Network, Automation, Operations, Administration; groups open on demand, the one holding the current page is always open, and what you leave open is remembered)
|
||
- Authentik OIDC login, roles (first user to sign in becomes admin), audit log
|
||
(changes made in the app, sign-ins and sign-outs with the IP they came from, new accounts, and the log's own
|
||
automatic trimming — attributed to "system"; settings changes show what changed, but never credentials)
|
||
- **Dashboard** — an overview of every system this app tracks, all sharing
|
||
one widget-card design (label + status badge, a small stat row, then its
|
||
own breakdown): DNS (domain/record counts per provider, cached records by
|
||
type), Secrets (monitored/expiring/expired, by type), and one widget per
|
||
integration — Tailscale by OS, Proxmox by node (VM/LXC counts too),
|
||
Dockhand by container state (plus host count), Semaphore and Gitea by
|
||
last-run status (plus private-repo count), and Synology's CPU/RAM
|
||
alongside its disk-health breakdown. Breakdowns render as a stacked
|
||
proportion bar with a legend — no charting
|
||
library, matching the rest of the app's plain-Tabler-CSS approach.
|
||
The Servers widget shows how many servers are online, offline, or have never
|
||
reported, which are offline and for how long, and any disk at or above the
|
||
usage threshold — decided by the same rules as the health alerts, so the
|
||
widget and the notifications always agree, and following the thresholds in
|
||
Settings even for viewers who can't open them.
|
||
The Domains widget shows how many registrations are tracked, which are
|
||
expired or expiring (soonest first), the next one to expire, and how many
|
||
couldn't be refreshed.
|
||
The Uptime Kuma widget shows the monitor count, how many are down, and how
|
||
many are matched to one of your servers.
|
||
The Proxmox Backup Server widget shows the datastore count and how many
|
||
stored snapshots have failed verification or were never verified.
|
||
The osTicket widget shows how many tickets are open, overdue, and awaiting
|
||
a staff reply.
|
||
- **Diagnostic Log** (admin-only) — every call this app makes to a DNS
|
||
provider or integration (Tailscale, Proxmox, Synology, Semaphore, Gitea,
|
||
Dockhand, Uptime Kuma, Proxmox Backup Server, osTicket), success or failure, with latency and the error message if it
|
||
failed — the last 500 calls, filterable by source/result, for
|
||
troubleshooting connectivity issues (ported from Sloth Manager's
|
||
provider-diagnostics log, generalized to cover every integration this app
|
||
has, not just DNS)
|
||
- **Secrets** — expiry tracking for API tokens/certs/passwords. An SSL
|
||
certificate can optionally be given a host:port to watch: the app opens a
|
||
real TLS connection (daily, and on demand via "Check now"), reads the
|
||
certificate's actual expiry, and keeps the date current — so a renewed cert
|
||
is picked up automatically and an unreachable host is flagged instead of
|
||
silently going stale. A secret that doesn't expire (a break-glass password,
|
||
a key with no end date) can be ticked "Never expires": it is listed with the
|
||
status "no expiry" and never raises an alert or reminder
|
||
- **IP Addresses (IPAM)** — inventory of IPs across vendors/locations,
|
||
with "Sync from Tailscale", "Sync from Proxmox", and "Sync from phpIPAM"
|
||
actions to pull in tailnet device IPs, VM/LXC IPs, and phpIPAM's own
|
||
addresses (never overwrites a manually-entered IP, or one a different sync
|
||
owns), and each entry now shows its matching DNS record(s) from the DNS
|
||
module's cache. Shares the Consistency page's excluded-ranges setting (see
|
||
below) so addresses that aren't interesting to track — a Docker bridge
|
||
network repeating on every host, say — can be hidden here too, with a
|
||
"Hide excluded addresses" toggle and a per-entry "Exclude…" shortcut to add
|
||
a range on the spot; managing ranges from either page updates the other
|
||
- **DNS** — zone/record management across Cloudflare, Loopia, Pi-hole, Azure
|
||
DNS, cPanel, and Technitium; providers are configured in-app (not via env
|
||
vars) and their credentials are encrypted at rest
|
||
- **Servers** — cron/systemd tracking across Debian/Raspbian servers via a
|
||
lightweight push agent (`agent/linux/`), Windows scheduled-task tracking
|
||
through a PowerShell agent (`agent/windows/`, see its README), plus manual
|
||
entries for things an agent can't see (Docker jobs, backups). The Servers page itself just lists
|
||
registered servers and (admin-only) adds new ones / issues agent tokens;
|
||
clicking a server opens its detail page with CPU/RAM/disk status, IP
|
||
addresses, matching DNS names (looked up from the DNS module's cache), and
|
||
its scheduled tasks — live hardware from Proxmox for VM/LXC-backed
|
||
servers, or from the agent's own hardware report for everything else,
|
||
both showing the same per-disk usage breakdown (an LXC's root filesystem
|
||
read straight from the host; a QEMU VM's actual mounts via its guest
|
||
agent, alongside the allocated size Proxmox already knew about without
|
||
one). Servers that report through the agent also get a **Trends** card: small
|
||
lines for CPU load, memory and each disk over the last 24 hours, 7 or 30 days
|
||
(a sample is kept about every ten minutes, for 35 days), and for a disk that is
|
||
filling, its rate of growth and roughly how many days until it is full — shown
|
||
only with at least a day of history. Proxmox-linked servers also get
|
||
start/stop/restart buttons right on the detail page. The detail page also has an **Admin Links** section
|
||
(operator/admin to add/edit/remove) for bookmarking that server's own
|
||
admin UIs — Dockge, Webmin, Cockpit, Portainer, or anything else reachable
|
||
by URL. **Operations → Admin Links** summarizes every server's admin links
|
||
in one sortable, searchable table (server, label, URL, an "Open" link, and
|
||
the same add/edit/delete as the per-server section — adding one here just
|
||
asks which server it belongs to), so finding or managing one doesn't mean
|
||
visiting each server's own page. Since not every server is a Proxmox VM, an admin can hide the
|
||
"Proxmox link" card per server ("Not a VM? Hide this" / "+ Show Proxmox
|
||
link options") — it stays visible regardless once a server actually is
|
||
linked, so unlinking is always reachable.
|
||
- **Tailscale**, **Proxmox**, **Synology**, **Semaphore**, **Gitea**,
|
||
**Docker**, **Uptime Kuma**, **Proxmox Backup Server**, and **osTicket**
|
||
each get their own top-level page (backed by the matching integration)
|
||
instead of living inside a shared Integrations browsing view:
|
||
- **Tailscale** — device list with online/authorized status, and
|
||
authorize/deauthorize/remove actions; a live device-count widget.
|
||
- **Proxmox** — VM/LXC status across every node in the cluster, with
|
||
start/restart/shutdown/stop actions; a live running/total widget. Each
|
||
online node also gets its own host-stats card — uptime, CPU usage/cores/
|
||
load average, RAM and swap usage, and per-storage usage (local, LVM-thin,
|
||
ZFS, NFS, etc). Supports self-signed certificates (common in homelab
|
||
setups).
|
||
- **Synology** — volume and disk health (read-only by design).
|
||
Supports self-signed certificates.
|
||
- **Semaphore** — Ansible run status per template across every
|
||
project, with a "Run" action to trigger a template; a live
|
||
template-count widget (with a last-failed warning).
|
||
- **Gitea** — repo list with each repo's last CI run status, and
|
||
re-running just the failed jobs in a run; a live repo-count widget
|
||
(with a failing-build warning).
|
||
- **Docker** — container status across every Docker host Dockhand
|
||
manages (one credential covers all of them), with
|
||
start/stop/restart actions, a host filter, image-update status per
|
||
container (from Dockhand's own cached update check, plus a button
|
||
to trigger a fresh one), and a live running/total widget (with an
|
||
updates-available count).
|
||
- **Uptime Kuma** — every monitor's status (up/down/pending/maintenance),
|
||
response time, and 24h/30d uptime, with certificate days remaining where
|
||
applicable. Each monitor is matched to one of your servers when its
|
||
target (an IP, or a TCP/HTTP hostname) lines up with that server's own
|
||
address or hostname, linking straight to it — so you can see what's
|
||
actually being watched on each box, not just a flat monitor list.
|
||
Uptime Kuma has no conventional REST API (the dashboard talks to it over
|
||
Socket.IO), so this reads its Prometheus `/metrics` endpoint instead and
|
||
parses that itself; read-only, no actions.
|
||
- **Proxmox Backup Server** — every configured datastore's usage and
|
||
snapshot count, the PBS host's own CPU/RAM/disk, and each stored
|
||
snapshot's verification status, since Proxmox VE only knows whether a
|
||
backup *ran*, never whether PBS's own verify pass on the stored data
|
||
still passes; a daily check alerts on any snapshot that's failed
|
||
verification or a datastore that couldn't be read. Read-only, no
|
||
actions (nothing here can prune, delete, or trigger a re-verify).
|
||
- **osTicket** — every currently open ticket, with its status, priority,
|
||
department, assigned staff member or team, requester, and two flags
|
||
worth a glance on their own: **overdue** and **awaiting our reply**.
|
||
osTicket's own REST API only supports *creating* tickets, not listing
|
||
them, so this reads osTicket's MySQL/MariaDB database directly with a
|
||
read-only user — the only integration here that isn't a REST API.
|
||
Read-only, no actions.
|
||
|
||
The Integrations page itself is now just a list of configured
|
||
integrations (name/type/status, visible to every role) with an
|
||
admin-only "Add integration" button and edit/enable/disable/delete
|
||
actions per row — the nine dedicated pages above are where you
|
||
actually use each one.
|
||
- Every table in the app is click-to-sort on any column (numbers, booleans,
|
||
and dates/text sort correctly regardless of how the column formats them)
|
||
and has an "Export CSV" button next to it that exports whatever's
|
||
currently sorted/filtered. Tables that can realistically grow large
|
||
(DNS zones/records, IP Addresses, Secrets, Servers, Audit Log, and each
|
||
integration's device/container/guest/repo/template list) are paginated,
|
||
20 rows per page by default — adjustable under Settings → Display — and
|
||
CSV export still covers every sorted/filtered row, not just the current
|
||
page.
|
||
The few small tables that have no search or sorting of their own (the
|
||
maintenance lists, tags, share links, API tokens and webhooks, the
|
||
Backup page's job and run lists, the comparison table) have an Export CSV
|
||
too, which writes the table as it is on screen — times as exact timestamps,
|
||
action buttons left out.
|
||
- **Settings** (admin-only) — notification channels (Gotify, ntfy, SMTP,
|
||
generic webhook) with per-channel test buttons, per-event toggles (DNS
|
||
record added/updated/deleted, daily secret-expiry reminder and daily
|
||
Tailscale key-expiry reminder — both sharing one configurable
|
||
time/timezone), badge-color customization for both DNS
|
||
providers and integration types, and a **Display** tab (date order,
|
||
12/24-hour clock, and rows-per-page for every paginated table) applied
|
||
consistently across the app.
|
||
|
||
All six integrations follow the same config-in-UI + encrypted-credentials
|
||
pattern, added (and edited — e.g. to rotate an expired API token without
|
||
recreating the whole integration) through **Integrations → Manage
|
||
integrations**. See [INTEGRATIONS.md](INTEGRATIONS.md) for exactly what
|
||
credential to create and what access it needs in each target system,
|
||
for every integration and DNS provider.
|
||
|
||
**Verified for real, end to end**: every module above — including all six
|
||
integrations, both their read-only views and their write actions
|
||
(start/stop/restart, trigger-a-run, authorize/deauthorize) — has been
|
||
exercised against the user's actual live homelab, not just built against
|
||
specs. That pass also found and fixed two real bugs: the Synology adapter
|
||
assumed HTTPS-only (the NAS is reached over plain HTTP), and the Tailscale
|
||
adapter read `online`/`isExitNode` fields that don't actually exist in the
|
||
real API response (fixed to derive them from `connectedToControl` and
|
||
`enabledRoutes`). See the git log for the full verification notes per
|
||
integration. (Uptime Kuma, Proxmox Backup Server, and osTicket, added
|
||
later, are not part of that "six" — see their own git log entries, and
|
||
[INTEGRATIONS.md](INTEGRATIONS.md), for what was and wasn't verified
|
||
against a real instance.)
|
||
|
||
Server and storage health is watched every 15 minutes: a server whose agent
|
||
stops reporting, a server disk / Proxmox storage / Synology volume passing a
|
||
usage threshold, and a Synology volume or disk that's degraded or failing each
|
||
raise one notification when the problem starts and one when it clears (both
|
||
thresholds are set under Settings → Notifications). Active problems are
|
||
remembered across restarts, so a rebuild doesn't re-alert them.
|
||
|
||
**Tags** — servers can be tagged (prod, media, rack-1, …) from their detail
|
||
page by operators and admins. Tags show as coloured chips on the Servers page,
|
||
which can be filtered by one or several tags (the filter is in the URL, so a
|
||
tag on a server's page links to everything sharing it), and they're searchable
|
||
from the global search box.
|
||
Admins manage tags under Settings → Tags: add tags before any server uses them (they're
|
||
offered as one-click suggestions when tagging), give any tag a colour of your choosing
|
||
(or leave it on the automatic one), rename tags, and delete them. Renaming to a name
|
||
that already exists merges the two, and both rename and delete rewrite every server
|
||
that carries the tag.
|
||
|
||
**Name generator** — Operations → Generator suggests server names (and usernames and
|
||
passwords, which are made in your browser and never stored). Server names are picked from
|
||
name lists: Swedish girl and boy names, Disney and Pixar characters, Norse mythology and
|
||
Astrid Lindgren to start with, or "Mixed" for all of them together. A name already used
|
||
by a server isn't suggested. Admins edit the lists under Settings → Names — add and remove
|
||
names, rename, delete or create lists, put a built-in list back as it was — and can
|
||
import the most common Swedish names from Skatteverket's open name statistics for
|
||
girls or boys over the latest one to five years. The import is shown to you first and only
|
||
changes a list once you add it and save. (Statistics Sweden used to publish this but
|
||
stopped after 2023.) Names are kept to letters, digits and hyphens so they work as
|
||
hostnames; å, ä and ö become a, a and o.
|
||
|
||
**Agents and what the server connects to** — the agents only push: the server replies "received" and nothing more, so it has no way to
|
||
make a server run anything. Each server has its own token (kept only as a hash), which can do one thing: replace that server's own report.
|
||
The Linux agent hands its token to curl on standard input and keeps its payload in a private temporary directory, so neither is visible
|
||
to other users on the machine, and its systemd unit runs with the usual restrictions (no new privileges, read-only system, private /tmp) and keeps only the three
|
||
root powers the agent uses — reading every user's crontab, switching user to list it, and seeing which program owns each socket.
|
||
On Windows the agent's folder is limited to SYSTEM and Administrators. The agent endpoint checks the token before it reads a report, takes
|
||
reports of several MB, and trims overlong text rather than rejecting the whole report. **After upgrading, re-run the install one-liner on
|
||
each server** to pick this up — an installed agent keeps its own copy of the script and doesn't update itself.
|
||
A few features connect to a host somebody typed in: the certificate check on a secret, the WHOIS server a registry names, and the port
|
||
scanner. These refuse this server itself (loopback), link-local addresses and the cloud metadata addresses (169.254.169.254 and its
|
||
relatives), and connect to the address they checked rather than looking the name up a second time. LAN hosts are fine for certificate
|
||
checks and scans; a WHOIS server must be public. IDs in a request (a device, a node, a DNS record) are checked against what a real ID
|
||
looks like before they go into a call to a connected system. `npm test --workspace server` covers all of this.
|
||
|
||
**Signing in** — through Authentik (OpenID Connect) with PKCE and a random `state`. The ID token's signature is checked against Authentik's
|
||
published keys, not just its contents, so the login doesn't rest on the connection to Authentik alone. A new session id is issued at sign-in. A
|
||
request that changes something is refused when it comes from another origin: the session cookie is SameSite=Lax, which doesn't stop another app on
|
||
the same parent domain, so the server also checks where each such request came from. A failed sign-in shows a plain message and is written to the
|
||
audit log (as `session` / `login_failed`, with the address and a short reason), and sign-in is limited to 20 attempts a minute per address.
|
||
Every response carries `frame-ancestors 'none'`, `X-Frame-Options`, `nosniff` and a no-referrer-to-other-sites policy. In production the app
|
||
refuses to start without a `SESSION_SECRET`, and warns if it is still the placeholder from `.env.example`.
|
||
Things to know: the first account to sign in becomes admin, so sign in yourself first on a new install. A session lasts up to 7 days after last use,
|
||
and disabling someone in Authentik does not end it — delete them on the Users page (or revoke the session on the Sessions page) and it ends at once.
|
||
If Authentik uses a certificate from an internal CA, point Node at the CA with `NODE_EXTRA_CA_CERTS=/path/to/ca.pem` rather than turning verification
|
||
off with `NODE_TLS_REJECT_UNAUTHORIZED=0`.
|
||
|
||
**Privacy** — a page every signed-in user can open that says what this
|
||
installation stores (accounts, sign-in sessions with their IP and browser, the audit
|
||
and diagnostic logs, server reports, the secrets tracker, credentials), where data
|
||
goes (Authentik, your integrations and DNS providers, the notification channels
|
||
that are switched on, domain registries), what's kept in the browser, who can see
|
||
what, and how to limit or remove data. Retention, integrations and channels are
|
||
read live from the installation; channel addresses are shown to admins only. Each
|
||
user sees their own account and sign-ins there and can download their own data
|
||
(account, sign-ins, audit-log entries) as a JSON file.
|
||
|
||
**Consistency** — a report of where IPAM, DNS and your servers disagree about
|
||
an address: the same address on two servers, a DNS record named after a server
|
||
that points somewhere it isn't, an IPAM entry labelled with a server's name at
|
||
the wrong address, addresses in use that IPAM doesn't list (with an "Add to
|
||
IPAM" button), and server addresses no DNS record points at. It only compares
|
||
data the app already holds — nothing is fetched when you open it — so it says how
|
||
many servers reported addresses and how fresh the synced DNS zones are. Only
|
||
private addresses are compared; ranges you exclude (Docker's, which repeat the same
|
||
subnet on many hosts — 172.16.0.0/12 is excluded by default, remove it if that's a
|
||
real LAN for you) are left out of every source; anything that's fine on purpose
|
||
can be ignored with a reason, and stays ignored. The excluded-ranges list is the
|
||
same one the IP Addresses page manages — edit it from either page and both
|
||
reflect the change.
|
||
|
||
**Domains** — when each domain registration expires, read from the registry
|
||
itself. The domains behind your DNS zones are picked up automatically (a zone
|
||
like `lab.example.se` resolves to the `example.se` registration that actually
|
||
expires); others can be added by hand. Each is looked up daily over RDAP where
|
||
the TLD offers it, and otherwise over WHOIS via IANA's referral — which is what
|
||
makes `.se`, `.nu` and `.io` work, since those aren't in the RDAP bootstrap.
|
||
You're reminded daily from N days before expiry (Settings → Notifications,
|
||
default 30) until it's renewed, and told when an expiry date couldn't be
|
||
refreshed for several days. Registries that don't publish an expiry (`.de`,
|
||
`.eu`) can be tracked but have no date to warn about. Private zones (`.lan`,
|
||
`.local`) are skipped.
|
||
|
||
**Automation failures** — every 15 minutes the app looks at the latest run of
|
||
each Semaphore template and each Gitea repo's latest workflow run. A failed one
|
||
raises a single notification (with the project/template or repo, run number, and
|
||
for Gitea the run's link), and another when a later run succeeds. It's
|
||
state-based, so a job that fails every night alerts on the first failure rather
|
||
than every night. A run that's still going, was cancelled, or was stopped by
|
||
hand leaves things as they were, and anything that couldn't be read (a Semaphore
|
||
project or Gitea repo that errored, or an integration that's down) is neither
|
||
cleared nor re-announced. The first check after upgrading only records what's
|
||
already failing, so old failures aren't announced. Toggle it under Settings →
|
||
Notifications. For Gitea this follows the repo's most recent run on any
|
||
workflow or branch, the same as the Gitea page shows.
|
||
|
||
**Alerts** (Operations → Alerts, visible to every role) lists everything that's
|
||
wrong right now in one place, instead of waiting for a notification or visiting
|
||
each page: servers that stopped reporting, full or nearly full disks and volumes
|
||
(critical from 95%), Synology volume/disk problems, failed or uncovered Proxmox
|
||
backups, failed Proxmox Backup Server verifications, container image updates,
|
||
secrets, domains and Tailscale keys that are expired or about to be, failed
|
||
Semaphore/Gitea runs, Uptime Kuma monitors that are down, overdue osTicket
|
||
tickets, and integrations whose calls keep failing. It runs the same checks that
|
||
send the notifications — so the two can't disagree — but ignores the on/off
|
||
toggles, since it's for looking at rather than being interrupted by. Problems
|
||
under a maintenance window stay listed, marked silenced and counted separately.
|
||
It also looks ahead: from an agent server's own history (see its Trends card), a
|
||
disk that is on course to be full within 14 days (Settings → Notifications → "Warn
|
||
when a disk will fill within"; 0 turns it off) is flagged with its rate of growth
|
||
and the days left — critical when that is three days or less. It needs at least
|
||
three days of steady growth to say anything, skips a disk that jumped once or
|
||
wobbles, and leaves out one already past the usual disk threshold, which has its
|
||
own alert. These forecasts appear on the page and the dashboard (and in alert
|
||
tickets if you've chosen disk problems); they are not sent as notifications. On
|
||
any alert that a maintenance window can silence, operators and admins get a
|
||
**Silence** button (1, 4 or 24 hours): it starts a maintenance window on that
|
||
server or integration — so everything about it goes quiet, which the toast says —
|
||
and it can be ended early under Maintenance.
|
||
It checks live (a recent result is reused for a minute; "Check now" forces a
|
||
fresh one), and anything it couldn't read is called out at the top rather than
|
||
quietly treated as fine.
|
||
|
||
**Alert tickets** (Settings → Alert tickets, admin only) opens a ticket in osTicket for an alert, through osTicket's own API. Every 15 minutes the
|
||
problems on the Alerts page are looked at, and one that is new and has lasted two checks in a row gets one ticket — never a second for the same problem,
|
||
and never one for something under a maintenance window or about osTicket itself. You choose which severities and kinds count (critical and warning by
|
||
default), and the Alerts page shows the ticket number on each alert that has one. If many problems appear at once — a network drop that makes thirty
|
||
things look down — they become one summary ticket instead of thirty. Problems already there when you switch it on are left alone unless you ask for
|
||
tickets for them too. osTicket's API can't close or update a ticket, so once it's open it's yours to close. It needs an API key made in osTicket (tied to
|
||
this server's IP address, allowed to create tickets), entered on the osTicket integration; "Send a test ticket" checks the whole chain.
|
||
|
||
**Maintenance mode** silences alerts about one server, integration, or DNS
|
||
provider while you work on it (server offline / disk, storage and Synology
|
||
health, Proxmox backup alerts, Proxmox Backup Server verification alerts, and
|
||
"integration down" for that service type).
|
||
For a power cut or a rack reboot, the "Many at once" choices at the top of the
|
||
list start a window on every server, every (enabled) integration, every
|
||
(enabled) DNS provider, or all of them in one go — asking first before
|
||
"Everything" — and "End all" on the Active list closes them together. Each is
|
||
still its own window, so any can be ended alone. Every window has a fixed end (5 minutes to 7 days) and expires on its own, and
|
||
a problem that began during a window and is still present when it ends alerts
|
||
then — a forgotten window can't hide an outage. A banner shows what's currently
|
||
silenced to every signed-in user. If you also run Uptime Kuma, the Maintenance
|
||
page can take its maintenance windows over: "Sync schedule" reads each window
|
||
(daily, weekly, one-off, cron or switched on by hand), finds the servers,
|
||
integrations and DNS providers its monitors are the address of, and makes a
|
||
window here for each, for the slot running now and the next
|
||
one — listed under Scheduled until it starts, then silencing alerts like any
|
||
other. Tick "Keep maintenance windows in step" on the Uptime Kuma integration
|
||
and this happens by itself every 15 minutes, so a daily window needs no
|
||
clicking at all; a window changed, switched off or deleted in Uptime Kuma is
|
||
followed, and one you end or cancel here by hand stays ended. Reading the
|
||
schedule needs a login on the Uptime Kuma integration (see INTEGRATIONS.md).
|
||
"Import now" is the older, simpler route: it only looks at what is in
|
||
maintenance this moment and starts a window for a duration you choose.
|
||
|
||
**Favourites and a narrow sidebar.** Hover (or tab to) a page in the sidebar and
|
||
click its star to pin it: pinned pages are listed under "Favourites" at the top
|
||
of the menu, are offered first in the search box, and follow you to any
|
||
browser, because they are saved with your user (the search box can also pin or
|
||
unpin the page you are on). A table's search words, status, tag and sort live
|
||
in the address (`/servers?status=offline`), so they survive a reload and can be
|
||
bookmarked; once something narrows the table a **Save view** button pins that
|
||
view too, listed under Favourites by its filters ("Servers not reporting"). A
|
||
button at the foot of the sidebar — or the `[` key
|
||
— narrows it to a strip of icons for more room on a laptop screen: a group's
|
||
pages then open in a small menu beside its icon, the alert and maintenance
|
||
counts stay visible, and your choice is remembered in that browser. On a phone
|
||
the sidebar is the same slide-out menu as ever.
|
||
|
||
**Getting around.** Ctrl/Cmd+K opens a search that also runs actions: go to any
|
||
page, switch light/dark or the density, start (or end) a maintenance window on
|
||
a server, integration or DNS provider ("silence elsa"), open the wall display,
|
||
sign out. "g" then a letter goes to a page (`g d` dashboard, `g a` alerts,
|
||
`g s` servers, `g m` maintenance, `g i` integrations, `g k` secrets, `g p` map,
|
||
`g w` wall display), "/" jumps to the page's table search, and "?" lists them
|
||
all, and "j" / "k" move down and up the rows of a table that opens a panel (Enter
|
||
opens the row you are on). Shortcuts for pages your role can't open are ignored,
|
||
and none fire while you are typing. On a table of Proxmox guests, Docker containers, Tailscale
|
||
devices, Uptime Kuma monitors, Gitea repositories or Semaphore templates, a
|
||
click (or Enter) on a row opens a panel with everything known about it, without
|
||
leaving the table.
|
||
|
||
**Map** (Infrastructure → Map) draws how things connect: which Proxmox host each
|
||
linked server runs on, which DNS names point at it (an A or AAAA record holding
|
||
one of the server's own addresses — nothing is guessed from names), and which
|
||
Uptime Kuma monitors watch it. Hover or tab to a box to light up its
|
||
connections; each box links to its page. A monitor Uptime Kuma can't be read for
|
||
leaves a note rather than a silent gap.
|
||
|
||
**Wall display** (`/wall`, also on the dashboard and the user menu) is a
|
||
full-screen status board for a spare monitor or tablet: the overall state in
|
||
large type, servers online, alerts, maintenance windows and failing integrations,
|
||
the problems themselves, and each integration's status, refreshing every 30
|
||
seconds with the screen kept awake where the browser allows. Esc returns to the
|
||
app.
|
||
|
||
**Alerts folded under their host.** A server can say which server it runs on (a
|
||
virtual machine on its Proxmox host): on its page, "Runs on" — and left alone it
|
||
is worked out when the server is linked to a Proxmox guest and exactly one
|
||
server is named after that guest's node. When the host stops reporting, the
|
||
guests' own "server offline" alerts are folded under the host's ("also takes down
|
||
anna, elsa") instead of being one alert each: they are held back like a silenced
|
||
alert, not counted, left out of notifications and osTicket tickets, and labelled
|
||
"caused by pve1" on the Alerts page. They are still recorded as down (for the
|
||
uptime ribbons and "Since you last looked"), and if the host comes back while a
|
||
guest is still down, that guest alerts then as new — an outage is never swallowed.
|
||
Links that loop back on themselves cover nothing, and setting one that would is
|
||
refused. "Nothing — it runs on its own" stops the guess for a server that isn't a
|
||
guest (a physical machine that happens to share a Proxmox node's name), so its
|
||
alerts always stand alone.
|
||
|
||
**Recurring maintenance** (Maintenance → Recurring) repeats a window on the days
|
||
and clock time you choose — "Sundays 02:00–04:00 on these servers" — in the time
|
||
zone of the browser it was made in, so 02:00 stays 02:00 across summer and winter
|
||
time. Each time becomes an ordinary maintenance window a week ahead (shown on the
|
||
timeline with vertical stripes, and in Scheduled), so any single one can be
|
||
cancelled and stays cancelled. Turning a schedule off or removing it takes back
|
||
the windows that haven't begun. Edit changes a schedule's name, days, time, length
|
||
or what it covers: the windows that haven't begun are made again from the new
|
||
settings (a single one cancelled by hand comes back too), and one already under
|
||
way keeps its times and ends on its own.
|
||
|
||
**Running a playbook** from an alert or a server: a server's page has a "Run a
|
||
playbook" card, and alerts about a server have a "Run…" button, which pick a
|
||
Semaphore template and run it limited to that server (ansible's `--limit`, which
|
||
you can edit to match the host name in your inventory — or untick it to run on
|
||
everything, which asks more sternly). Semaphore is told who started it, the run
|
||
shows waiting → running → success or failed, and the audit log records what ran
|
||
and where. Operators and admins only.
|
||
|
||
**Updates** (Operations → Updates) shows what each agent says is waiting to be
|
||
installed — how many, how many are security fixes, whether a restart is due, and
|
||
how long updates have been waiting — plus the Docker containers with a newer image.
|
||
The Linux agent asks apt, dnf or zypper (only what they already know; nothing is
|
||
installed or refreshed — that one question is asked outside the agent's sandbox, which `dnf` and `zypper` need) and the Windows agent asks Windows Update (at most every six
|
||
hours, cached under `%ProgramData%\HomelabManager`). A server whose agent hasn't
|
||
said — an older agent, or another package manager — shows "not reported", never "up
|
||
to date"; run its install command again to update its agent (how, and how to
|
||
tell it worked: [AGENT_UPDATE.md](AGENT_UPDATE.md)).
|
||
|
||
**Acknowledging and handing over alerts.** On the Alerts page, **Acknowledge…** (operators) says
|
||
"somebody is on this": an optional note, who has it (an administrator or operator), and how long it should
|
||
be left alone (an hour to a week, or until the alert is gone). It changes nothing about the problem — the
|
||
alert is still raised, still counted by `/metrics` and still on the wall display — but the alert shows who
|
||
has it and why, the sidebar count, the dashboard strip and the Alerts cards count only what nobody is on,
|
||
and the list can be filtered to "nobody is on it" or "handed to me". An acknowledgement that runs out puts
|
||
the alert back among the unattended; it goes by itself once the alert has been gone for half an hour, so
|
||
the same problem returning next month is not "still being dealt with". It is in the audit log and in the
|
||
server's history.
|
||
|
||
**Incidents** (Operations → Incidents). Each time an alert is raised and later goes away is recorded as an
|
||
incident, with when it began and ended and how bad it got, so "what happened on Tuesday night?" has an answer
|
||
after the alert is gone. Open one for the whole story in order: the alert, who acknowledged it and why, the
|
||
maintenance windows, what was changed on the server, update runs, other alerts about the same thing that
|
||
began around the same time, and the notes people wrote (operators can add them; the author or an
|
||
administrator can remove one). Incidents are recorded from the alerts as they are collected and from a look
|
||
every five minutes, so one that comes and goes between two looks may be missed. An alert is only called
|
||
resolved after it has been missing for a couple of minutes in a row — thirty when a check couldn't run, and
|
||
never in the first minutes after the app starts, when server alerts are held back on purpose. Resolved
|
||
incidents are kept for 400 days. The weekly digest has an *Incidents* section.
|
||
|
||
**Database backups** (Settings → Backup). A copy of Homelab Manager's own database is taken every day (03:30
|
||
in the notification time zone, the newest 14 kept; on unless you turn it off), checked as it is made, and
|
||
kept in `data/backups/`. The page lists them with **Download**, **Check**, **Restore…** and **Delete**,
|
||
makes one now (**Back up now**), takes one from somewhere else (**Upload a backup…**) and sets the schedule.
|
||
A restore is checked first, then staged, and takes effect the next time the app starts — restart it
|
||
(`docker compose restart homelab-manager`); the database that was in use is kept as a "before a restore"
|
||
backup, so a restore can be undone. A backup made by a *newer* version than the one running is refused.
|
||
If the newest backup gets more than two days old, or a scheduled one fails, it is an alert (and a message).
|
||
**A backup does not contain `CREDENTIALS_ENCRYPTION_KEY`**, which decrypts the credentials stored in it,
|
||
and it is still on the same machine until you copy it away: see [BACKUP.md](BACKUP.md).
|
||
|
||
**Update runs** (Updates → Update…, operators). Apply a server's waiting updates in
|
||
one go: pick the Semaphore playbook that does it, and Homelab Manager puts the server
|
||
under maintenance (so nothing alerts while it works and restarts), runs the playbook
|
||
limited to that one server, follows it, waits for the server's agent to report again,
|
||
and then says how many updates are still waiting and whether a restart is due before
|
||
ending the window it made. The runs are listed on the Updates page and in the server's
|
||
history, survive a restart of this app, and end as *failed* (with the window ended, so
|
||
the alerts can speak) if the playbook fails, Semaphore stops answering, the server
|
||
doesn't report again within 30 minutes, or it takes more than three hours. "Stop
|
||
following" ends the window and stops watching; it can't stop a playbook already running
|
||
in Semaphore. A message goes to your channels when a run ends (a toggle under *What to
|
||
send*). It never restarts the server itself — the playbook does, if it is written to.
|
||
|
||
**Host health and automatic agent updates.** The Linux agent (version 4) also reports services that have
|
||
failed, each disk's SMART verdict, temperature and wear, and ZFS pool state. They show on a server's page
|
||
(*Host health*) and become alerts — a failed service is a warning under its own kind, a failing disk or a pool that isn't
|
||
ONLINE is critical — with the same maintenance silencing, notifications and runbook links as other alerts. Disk space
|
||
heading for full was already forecast from each server's history (alert, weekly digest, trend note); `/metrics`
|
||
now carries it too as `homelab_server_disk_days_to_full`. **Servers → Update agents automatically** (off by default) lets
|
||
an agent that is behind download the newer script from here, check it against a SHA-256 the server gives, and replace itself.
|
||
How it works and what it can't do: [AGENT_UPDATE.md](AGENT_UPDATE.md).
|
||
|
||
**Runbooks.** Write down what to do when something is wrong — "if elsa is down,
|
||
check the UPS first, then…" — on a server's page (the Runbooks card) or an
|
||
integration's card. A note can be for anything about the thing, or for one kind of
|
||
alert (a disk filling up). On the Alerts page an alert about a server or integration
|
||
shows a Runbook link when a note fits it, and opens it in a side panel with the notes
|
||
that fit that alert first. Everyone signed in reads them; operators write them. The
|
||
text is plain: a blank line is a new paragraph, `- ` a list, ``` around lines a block
|
||
of commands, backticks inline code; links become clickable, and nothing typed in a
|
||
note can run as HTML.
|
||
|
||
**Backup coverage** (Infrastructure → Backup coverage) answers "what isn't backed
|
||
up?" for every Proxmox guest: is a backup job covering it, when was it last backed up
|
||
(from the newest snapshot on a Proxmox Backup Server, or the last successful Proxmox
|
||
backup task that names the guest), and did that go well — Recent backup, Stale (older
|
||
than 1, 2, 3, 7 or 14 days, your choice), Failed, No backup, or Unknown (a job covers it
|
||
but nothing says when it last ran, typical when backups go somewhere other than a
|
||
Backup Server — never guessed at). Worst first, searchable, with CSV, and the weekly
|
||
digest lists what needs a look. A guest whose newest backup is older than **Settings →
|
||
Notifications → "A guest's backup is too old after"** (48 hours by default; 0 is off) is
|
||
also an alert of the Backups kind — a warning, critical at three times the limit — with a
|
||
runbook link like any other, sent once a day with the other backup messages (under the
|
||
Proxmox backup toggle) and counted in `/metrics` (`homelab_backup_guests`,
|
||
`homelab_backup_last_age_seconds`). A server that is a guest can have its own limit
|
||
(a weekly backup is fine at eight days). Failed backups already raise their own alerts —
|
||
the latest failing run on a node, and snapshots that fail verification — so those aren't
|
||
repeated per guest. The page's own "Stale after" selector is only a view.
|
||
|
||
**Alert limits per server.** On a server's page an administrator can give it limits of
|
||
its own — offline after, disk usage percentage, the disk-forecast window, and (for a
|
||
Proxmox guest) how old its backup may be — and per disk, either a limit or "no alerts
|
||
for this disk". Whatever is left empty follows Settings, so changing the global limit
|
||
still reaches every server that hasn't said otherwise. They apply everywhere the global
|
||
ones did: the alerts, the notifications, the dashboard, the map, the forecast, the
|
||
digest and `/metrics`.
|
||
|
||
**Inventory** (Infrastructure → Inventory) keeps the hardware behind it all: name and
|
||
kind, maker, model, serial, where it sits (and rack unit), when it was bought and for
|
||
how much, when its warranty ends, its typical power draw, and which server it is.
|
||
Summary cards show how much is under warranty (and what ends within 90 days), the total
|
||
draw, and — with a price per kWh set at the foot of the page — a rough yearly running
|
||
cost. Everyone signed in can look; operators keep it up to date; the weekly digest
|
||
mentions a warranty ending within 60 days.
|
||
|
||
**Roles from groups** (Settings → Sign-in, off until switched on): name the groups
|
||
that mean administrator and operator, and at each sign-in a person's role follows the
|
||
groups the identity provider (Authentik) reports; everyone else becomes a viewer, or
|
||
keeps what they have. "Check" shows what each person would become from the groups they
|
||
had last time, before you switch it on. Safeguards: a sign-in with no groups at all (a
|
||
wrong claim name) leaves roles alone, the only administrator is never demoted by a
|
||
group rule, the first person ever is still the administrator, and while it is on the
|
||
Users page shows roles instead of letting you set them. The Users page also shows the
|
||
groups each person had at their last sign-in.
|
||
|
||
**Prometheus and webhooks** (Settings → API and webhooks). `/metrics` answers in
|
||
Prometheus's text format — servers up or not, load, memory, disks, waiting updates,
|
||
agent versions, alert counts, which integrations work, maintenance, what is about to
|
||
expire — to a request with a metrics token (a bearer token made on that page, shown
|
||
once, only its hash kept). Event webhooks send a signed JSON message to a URL when an
|
||
alert begins or ends or maintenance starts or finishes, for Home Assistant, n8n or a
|
||
status board. Both are described, with the exact series and message formats, in
|
||
[API.md](API.md).
|
||
|
||
**Weekly digest** (Settings → Notifications, off until switched on) sends one message a
|
||
week through your notification channels: 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 — each topic only if it has something to say, and "a quiet
|
||
week" when nothing does. "Preview" shows what it would say right now and "Send it now"
|
||
sends it at once. Details in [NOTIFICATIONS.md](NOTIFICATIONS.md).
|
||
|
||
**Agent versions.** Each agent script says its version in every report, and Homelab
|
||
Manager compares it with the scripts it serves, so a server whose agent is behind is
|
||
marked on the Servers page, on its own page and on the Updates page (which counts them).
|
||
How to update one: [AGENT_UPDATE.md](AGENT_UPDATE.md).
|
||
|
||
**Customising the dashboard.** Customise (top of the dashboard) lets you move each
|
||
card earlier or later among its neighbours and hide the ones you don't use —
|
||
hidden cards stay listed, dimmed, while you arrange so they can be brought back,
|
||
and Reset returns the default. It is saved with your user, so it follows you to
|
||
any browser, and it is yours alone.
|
||
|
||
**Comparing servers.** On the Servers page, Compare lets you pick two to four
|
||
servers and open their load, memory or a disk on one chart (24 hours, 7 or 30
|
||
days), each line with its own colour and dash pattern and a table of now, average
|
||
and peak beside it. Servers that don't report through an agent have no history
|
||
to draw. The Servers page also has a search box and a "not reporting /
|
||
reporting" filter, and the dashboard links to the not-reporting ones.
|
||
|
||
**Share links** (Settings → Share links, administrators only) make an address
|
||
that opens a read-only wall display **without signing in**, for a TV or someone
|
||
who only wants to know if things are up. Each link has a name, how long it works
|
||
(until removed, 7 days … a year) and how much it shows: *numbers only* (servers
|
||
online, alert counts, what is in maintenance, integrations failing — never a
|
||
name) or *with names* (also the text of the alerts, what is in maintenance and
|
||
the integrations' names — never addresses, tokens or settings). The picture is
|
||
built on the server, so nothing else leaves it. The secret in the address is
|
||
shown once; only a hash is stored, a link that never existed, ended or was
|
||
removed answers the same way, and making and removing links are in the audit log
|
||
(without the secret). It is as private as the address: remove it when it isn't
|
||
needed.
|
||
|
||
**Status pages** are the other thing a share link can open: a page for family or housemates
|
||
that answers "is the movie server up?" without a sign-in and without anything that isn't
|
||
theirs to see. Pick **A status page** when making a link, then choose what is on it and what
|
||
each thing is called ("Movies and TV", "Family photos"): each is a server (reporting, or not
|
||
— judged by its own limits), an integration (its latest calls work, or don't) or an Uptime
|
||
Kuma monitor. It says *Working*, *Not working*, *Being worked on* (under a maintenance
|
||
window) or *Can't tell right now*, with the 30-day figure where one is known, a heading and
|
||
an optional message ("Movies are being updated tonight"). The page follows the device's
|
||
light or dark setting and looks again every 30 seconds. Whoever has the address is given only
|
||
the names you chose and those states — no addresses, no ids, no alert text, nothing about
|
||
what the thing really is — and a status page's address doesn't open the wall display (or the
|
||
other way round). Uptime Kuma is asked at most every 30 seconds however many people look. Up
|
||
to 30 things per page.
|
||
|
||
**A Grafana dashboard** for the `/metrics` series: Settings → API and webhooks → *Download
|
||
the dashboard*, then in Grafana Dashboards → New → Import and pick your Prometheus when
|
||
asked. It has rows for what needs attention, servers (with a server picker), disks (usage,
|
||
filling up, SMART health, SSD wear, temperature, ZFS pools), backups (guests by state, age
|
||
of each newest backup, the app's own backup) and secrets, power and the app itself. It is
|
||
built from the same code as `/metrics`, and a test checks that it only asks for series that
|
||
are really served. See [API.md](API.md).
|
||
|
||
**Since you last looked.** The dashboard opens with a card on what happened
|
||
since you last pressed "Got it" (the first time, the last day; never more than
|
||
two weeks): servers that stopped reporting or filled a disk, services that
|
||
stopped answering, and maintenance that began or ended — each problem and its
|
||
recovery folded into one line ("elsa was offline for 12 min — reporting again";
|
||
a problem that hasn't ended says "still offline"). Operators and admins also see
|
||
how many changes other people made, with a link to the audit log. Nothing to say
|
||
means no card. The mark is stored on your user, so it follows you to any browser.
|
||
|
||
**Uptime ribbons.** Servers (list, cards and the server's page) and integration
|
||
cards show a strip of one bar per day for the last 30 days — green for a day with
|
||
nothing wrong, amber for some time down, red for half a day or more, grey where
|
||
nothing is known — and the share of time up. It is worked out from the moments
|
||
the health checks write in the audit log (a server stopped reporting / reported
|
||
again; an integration's calls started failing — the same threshold as the failure
|
||
alert — / worked again), so it can only be as old as those records: servers go
|
||
back to when they were added, integrations to the first time this version ran.
|
||
Integrations are tracked per kind of service, as the health checks are.
|
||
|
||
**Maintenance timeline.** The Maintenance page draws the running and scheduled
|
||
windows along a time axis (the next 24 hours, 7 days or 30 days), one row per
|
||
server, integration or DNS provider and a top row for "anything in
|
||
maintenance", so overlaps and gaps are visible. Windows mirrored from Uptime
|
||
Kuma are striped. The tables below still list the same windows.
|
||
|
||
**Times as people say them.** "Last seen", sync times, session activity and
|
||
similar columns read "5 min ago" and show the exact date and time, in the format
|
||
chosen under Settings → Display, on hover. Exports and the audit log keep exact
|
||
times.
|
||
|
||
**Activity.** Operators and admins see an Activity card on each server's page:
|
||
what changed on it and who changed it, the moments the health check saw it stop
|
||
reporting (and report again) or a disk fill (and recover) — now written to the
|
||
audit log as they happen — and its maintenance windows, including ones set up by
|
||
the Uptime Kuma sync. **Getting started**: until the basics are in place, an
|
||
admin's dashboard shows a checklist (an integration, a server and agent, DNS, a
|
||
secret, notifications, a second user) whose ticks come from what actually
|
||
exists; it can be hidden, and brought back from the search box.
|
||
|
||
**Accessibility.** There is a skip-to-content link, labelled landmarks, visible
|
||
keyboard focus, and page changes are announced to screen readers; sortable table
|
||
headings are real buttons; every form field is tied to its label; status is
|
||
never colour alone; the search box and dialogs are proper dialogs (keyboard
|
||
trapped and restored); and the text colours were checked against the contrast
|
||
minimum in both themes. Motion is turned down for those who ask the system to.
|
||
|
||
**Ports** — each server's detail page has a Ports card for finding free ports
|
||
and remembering what each one is for. "Scan…" runs a TCP scan of a port range
|
||
from the app against the server's address (private addresses only, up to
|
||
20,000 ports at a time) and lists what's open plus the ranges that were
|
||
confirmed free; a free range can be clicked to reserve a port. Any port can
|
||
carry a service name and a comment, and a port with a note counts as taken
|
||
even when nothing is listening. The agent also reports what is bound on the
|
||
host (`ss`), which catches services listening on localhost only — a scan from
|
||
elsewhere can't see those, so they'd otherwise look free. Re-run the agent
|
||
install one-liner on a host to pick that up.
|
||
|
||
**Network → Ports** is the cross-server counterpart: one page listing every
|
||
port every agent currently reports as listening, across all servers at once
|
||
(protocol, address, process, last report time), each linking back to its
|
||
server. Below that, a separate, manually-maintained table is for the ports
|
||
this app can't see on its own — a router's port forward, an edge firewall
|
||
rule, a cloud security group — the same reason people keep a spreadsheet of
|
||
"what did I open and why." Each entry has a label, the external port/protocol,
|
||
an optional link to a tracked server (plus its own internal port, when NAT
|
||
changes it) or a freeform destination, a free-text "source" (which
|
||
router/firewall/service it's actually configured on — this app doesn't talk
|
||
to any firewall, so it can't manage or verify the rule, only record it), and
|
||
a comment. Viewers can see both tables; adding, editing, or deleting a manual
|
||
entry needs operator or admin.
|
||
|
||
The app is installable as a PWA — "Install app" / "Add to Home Screen" from the
|
||
browser gives it its own icon and a standalone window on phone or desktop. This
|
||
needs the site to be served over HTTPS (browsers only offer install on secure
|
||
origins; `localhost` also counts). The bundled service worker deliberately
|
||
caches nothing, so an installed copy always shows the current build.
|
||
|
||
**More documentation**: [ROLES.md](ROLES.md) — who can see and do what;
|
||
[NOTIFICATIONS.md](NOTIFICATIONS.md) — every notification the app sends and when;
|
||
[INTEGRATIONS.md](INTEGRATIONS.md) — the credentials each integration needs;
|
||
[DATABASE.md](DATABASE.md) — the database tables, columns and relationships;
|
||
[BACKUP.md](BACKUP.md) — what to back up, how (also while it runs), how to restore, and how to check it.
|
||
|
||
## Requirements
|
||
|
||
- Node.js 20+
|
||
- An Authentik instance reachable from wherever this app runs
|
||
|
||
## 1. Set up an Authentik application
|
||
|
||
1. Create an **OAuth2/OpenID Provider**:
|
||
- Redirect URI: `<APP_BASE_URL>/auth/callback`
|
||
- Scopes: `openid`, `email`, `profile`
|
||
2. Create an **Application** using that provider, and assign the users/groups
|
||
who should be able to sign in — Authentik controls who can authenticate;
|
||
the app's own admin/operator/viewer roles control what they can do once in.
|
||
3. Copy the provider's issuer URL, client ID, and client secret into `.env`.
|
||
|
||
## 2. Local development
|
||
|
||
_Tests:_ `npm test --workspace server` runs the server's regression tests (Node's built-in runner, no extra setup) — among them a check that an ID in a
|
||
request can't be turned into a different call to a connected system (Tailscale, Proxmox, Gitea, Dockhand, Cloudflare, Azure).
|
||
|
||
```bash
|
||
cp .env.example .env # fill in AUTHENTIK_*, SESSION_SECRET, CREDENTIALS_ENCRYPTION_KEY
|
||
npm install
|
||
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. SQLite data lands in `./data` (gitignored).
|
||
|
||
Generate `SESSION_SECRET` and `CREDENTIALS_ENCRYPTION_KEY` with:
|
||
|
||
```bash
|
||
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
|
||
```
|
||
|
||
## 3. Run with Docker
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
# edit .env
|
||
docker compose -f docker-compose.dev.yml up -d --build # build locally
|
||
# or, once an image is published to your registry:
|
||
docker compose up -d
|
||
```
|
||
|
||
The app listens on `HOST_PORT` (default `3000`); SQLite data persists in
|
||
`./data` on the host.
|
||
|
||
**Telling a dev copy from production:** set `ENVIRONMENT_NAME` (e.g. `Dev`) and
|
||
optionally `ENVIRONMENT_COLOR` in that instance's `.env` (or under `environment:`
|
||
in its compose file). The sidebar then takes the colour, a badge with the name
|
||
sits next to the title and on the sign-in page, and the browser tab reads
|
||
`[Dev] Homelab Manager`. The colour is a name (`red`, `orange`, `amber`, `green`,
|
||
`teal`, `blue`, `purple`, `pink`, `gray`) or a hex value such as `#b45309`; a
|
||
name alone gets orange. Leave both unset on production and nothing changes.
|
||
Restart the container after changing them.
|
||
|
||
### arm64 (Raspberry Pi, Apple silicon, ARM servers)
|
||
|
||
Two compose files, one to build the image and one to run the published one:
|
||
|
||
```bash
|
||
# On any machine with Docker: build the arm64 image and push it to the registry
|
||
docker compose -f docker-compose.arm64.build.yml build
|
||
docker compose -f docker-compose.arm64.build.yml push
|
||
|
||
# On the arm64 machine: pull that image and run it (no build there)
|
||
docker compose -f docker-compose.arm64.yml pull
|
||
docker compose -f docker-compose.arm64.yml up -d
|
||
```
|
||
|
||
`docker-compose.arm64.build.yml` can also build and run right on an arm64 machine
|
||
(`up -d --build`). Building on x86 goes through QEMU emulation — slower, and it needs
|
||
a one-time `docker run --privileged --rm tonistiigi/binfmt --install arm64`.
|
||
|
||
Both files use the image `gitea.labsconnect.se/bobban/homelabmanager-homelab-manager:arm64`.
|
||
Set `IMAGE_REPO` and/or `ARM64_TAG` in `.env` to use another registry or to pin a release
|
||
tag (e.g. `ARM64_TAG=1.4.0-arm64`). The arm64 tag is kept separate from the default image,
|
||
so the existing `docker-compose.yml` is unaffected. A `.dockerignore` keeps host
|
||
`node_modules`, `.env` and `data/` out of the build.
|