Files
Homelab-manager/ROLES.md
T
bobbanandClaude Sonnet 5.5 3d9a2310bb Runbooks per alert kind, high-vulnerability threshold, wall display extras
A "What to do" note (text and/or link) can be written once for a whole kind of alert and
shows beside every alert of that kind; alerts now carry their kind and source type.
New optional setting: warn when a Docker host has N or more high vulnerabilities (off by
default). The wall display gains tiles (Hetzner and game servers running, critical
vulnerabilities, stuck downloads) and a summary line for each group of integrations,
also in share links. Migration 0074; docs and tests included.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-27 21:15:45 +01:00

199 lines
18 KiB
Markdown

# Roles & menu access
Homelab Manager has three roles, ranked lowest to highest: **viewer**,
**operator**, **admin**. The first person to sign in becomes admin;
everyone after that starts as viewer until an admin changes their role
under **Administration → Users**.
A role can do everything the roles below it can, plus what's listed for
it — operator includes everything viewer has, admin includes everything
operator has.
## Sidebar menu, by role
✅ = the menu item appears for that role · ❌ = it's hidden entirely (not
just disabled) — a group that would end up with zero visible items
disappears too, and a group left with exactly one just shows as that
page's own top-level link.
| Menu item | Path | Viewer | Operator | Admin |
|---|---|:---:|:---:|:---:|
| Dashboard | `/` | ✅ | ✅ | ✅ |
| Alerts (Now, History, Noise) | `/alerts` | ✅ | ✅ | ✅ |
| My work | `/my-work` | ❌ | ✅ | ✅ |
| **Infrastructure** | | | | |
| Servers | `/servers` | ✅ | ✅ | ✅ |
| Proxmox | `/proxmox` | ✅ | ✅ | ✅ |
| Synology | `/synology` | ✅ | ✅ | ✅ |
| Docker | `/docker` | ✅ | ✅ | ✅ |
| Hetzner Cloud | `/hetzner` | ✅ | ✅ | ✅ |
| Game servers | `/game-servers` | ✅ | ✅ | ✅ |
| Tailscale | `/tailscale` | ✅ | ✅ | ✅ |
| **Apps** | | | | |
| Home Assistant | `/home-assistant` | ✅ | ✅ | ✅ |
| Jellyfin | `/jellyfin` | ✅ | ✅ | ✅ |
| Media managers | `/media` | ✅ | ✅ | ✅ |
| Immich | `/immich` | ✅ | ✅ | ✅ |
| Paperless-ngx | `/paperless` | ✅ | ✅ | ✅ |
| Nextcloud | `/nextcloud` | ✅ | ✅ | ✅ |
| Authentik | `/authentik` | ✅ | ✅ | ✅ |
| **Backups** | | | | |
| Backup coverage | `/backups` | ✅ | ✅ | ✅ |
| Proxmox Backup | `/pbs` | ✅ | ✅ | ✅ |
| Duplicati | `/duplicati` | ✅ | ✅ | ✅ |
| **Network** | | | | |
| DNS (and Domains) | `/dns` | ✅ | ✅ | ✅ |
| Network devices | `/network/devices` | ✅ | ✅ | ✅ |
| Proxy hosts | `/proxy-hosts` | ✅ | ✅ | ✅ |
| IP Addresses | `/ipam` | ✅ | ✅ | ✅ |
| NetBox | `/netbox` | ✅ | ✅ | ✅ |
| Ports | `/ports` | ✅ | ✅ | ✅ |
| Consistency | `/consistency` | ✅ | ✅ | ✅ |
| **Monitoring** | | | | |
| Endpoints | `/endpoints` | ✅ | ✅ | ✅ |
| Alert rules | `/alert-rules` | ✅ | ✅ | ✅ |
| Heartbeats | `/heartbeats` | ✅ | ✅ | ✅ |
| Uptime Kuma | `/uptime-kuma` | ✅ | ✅ | ✅ |
| UPS | `/ups` | ✅ | ✅ | ✅ |
| Prometheus | `/prometheus` | ✅ | ✅ | ✅ |
| Speedtest | `/speedtest` | ✅ | ✅ | ✅ |
| Service levels | `/service-levels` | ✅ | ✅ | ✅ |
| **Automation** | | | | |
| Semaphore | `/semaphore` | ✅ | ✅ | ✅ |
| Gitea | `/gitea` | ✅ | ✅ | ✅ |
| n8n | `/n8n` | ✅ | ✅ | ✅ |
| Secrets (a top-level entry) | `/secrets` | ✅ | ✅ | ✅ |
| **Operations** | | | | |
| Maintenance | `/maintenance` | ✅ | ✅ | ✅ |
| Updates (and Patch plans) | `/updates` | ✅ | ✅ | ✅ |
| Coming up | `/coming-up` | ✅ | ✅ | ✅ |
| To do | `/todo` | ✅ | ✅ | ✅ |
| osTicket | `/osticket` | ✅ | ✅ | ✅ |
| **Records** | | | | |
| Monthly report (and quarterly, annual) | `/reports` | ✅ | ✅ | ✅ |
| Costs | `/costs` | ✅ | ✅ | ✅ |
| Change log (and the raw audit log, `?view=audit`) | `/changes` | ❌ | ✅ | ✅ |
| **Reference** | | | | |
| Map (Connections, and Dependencies) | `/map` | ✅ | ✅ | ✅ |
| Inventory (and Racks, Labels, Lifecycle) | `/inventory` | ✅ | ✅ | ✅ |
| Admin Links | `/admin-links` | ✅ | ✅ | ✅ |
| Generator | `/generator` | ✅ | ✅ | ✅ |
| **Administration** | | | | |
| Integrations | `/integrations` | ✅ | ✅ | ✅ |
| Diagnostic Log (Integrations → Call log) | `/integrations?view=calls` | ❌ | ❌ | ✅ |
| Users | `/users` | ❌ | ❌ | ✅ |
| Sessions (Users → Signed in now) | `/users?view=sessions` | ❌ | ❌ | ✅ |
| Settings | `/settings` | ❌ | ❌ | ✅ |
| **Outside the menu** | | | | |
| API tokens (user menu) | `/api-tokens` | ✅ | ✅ | ✅ |
| Privacy (footer link) | `/privacy` | ✅ | ✅ | ✅ |
So in practice: **every page is visible to every role except a few** — *My work* and the *Change log* (with the raw audit log) need operator; *Users* (with *Signed in now*) and *Settings* need
admin; and the *Call log* tab of Integrations needs admin (operators and viewers see Integrations without it). The sections that used to be pages of their own — Sessions, the audit log, the
Diagnostic Log, Dependencies, Domains — now live inside those pages, and their old addresses redirect there.
## Being able to see a page isn't the same as being able to change things
Almost every page above is visible to viewers, but most of the buttons
on them aren't — a viewer can look at everything but can't act on
anything. Operators can use the page's normal working actions (starting
a container, syncing DNS, adding a secret, opening a maintenance
window…). Some actions on otherwise-viewer-visible pages are held back
even further, to admin only:
- **Integrations & DNS providers**: any operator can use an integration
once it's configured (start/stop a guest, run a template, sync DNS
records, etc.), but adding, editing, testing, or deleting an
integration or DNS provider is admin-only.
- **Servers**: registering a new server, rotating its agent token, and
editing/deleting a server are admin-only; tagging a server and
linking/unlinking it to a Proxmox guest just need operator.
- **Tags**: creating, renaming, recoloring, or deleting a tag is
admin-only (applying an existing tag to a server needs operator).
- **Ports**: everyone can see both the agent-reported and manual tables;
adding, editing, or deleting a manual port opening needs operator.
- **Admin Links**: everyone can see and open every server's admin
bookmarks, from that server's own page or the summary page; adding,
editing, or removing one needs operator, from either place.
- **Generator**: everyone can use it; the name lists it picks server names from
are edited under Settings → Names, which is admin-only (and so is importing
names from Skatteverket).
- **Alert tickets**: everyone sees which alerts have an osTicket ticket (a
badge on the Alerts page, linking to the ticket in osTicket); switching the
feature on, choosing what opens a ticket, and sending a test ticket are
under Settings → Notifications → Alert tickets, which is admin-only. **Closing a ticket** along with an alert (the tick box in the Close drawer, for one alert or several picked together) is an operator's, like closing the alert; the login it writes with, and **Test closing**, are administrators'.
- **Runbooks**: everyone reads them (on a server's page, an integration's card, the *What to do* link beside an alert for a whole kind of alert,
next to an alert); writing, editing and removing one needs operator.
- **Inventory**: everyone can see the hardware (and print its labels); adding, editing and removing needs
operator, and so does *Refresh from agent*; the price of power used for the running cost is admin-only.
- **Bulk actions** (the bar that appears when rows are ticked) need the same role as the single action: operator to acknowledge, snooze, close, silence, tag, change hardware and undo any of those; administrator for *Runs on…* on several servers
(and its undo). Viewers do not see the tick boxes. The **Noise** tab of Alerts is for everyone signed in.
- **API tokens** (user menu): anyone signed in makes, sees and removes their own, and nobody else's; a token can only read (`GET /api/v1`), sees what its owner sees, and is removed with its owner. The chart ranges and history are for everyone signed in.
- **My work** is shown to operators and administrators and only ever lists their own alerts, maintenance and update runs; the buttons on it (change an acknowledgement, extend or end a window) need operator, like the pages they come from.
**Settings search** is part of Settings, which is administrators'.
- **Network devices** (Network → Network devices): everyone can see the devices, networks and Wi-Fi names read from UniFi controllers; **Read now** and putting a device under maintenance need operator; adding the UniFi
integration itself (a key or login) is an administrator's job, like any integration.
- **Docker vulnerabilities** (Docker page): everyone signed in sees the counts and the critical findings from Dockhand's scans; nothing on the page starts a scan or changes anything. Switching the alert off is in Settings → Notifications (administrators).
- **Docker containers** (Docker page): everyone signed in sees each container and what is wrong with it; start, stop and restart need operator; **Leave alone** (no alerts for a container) and the list in Settings are administrators'.
- **Away mode** (Settings → Notifications → When): administrators start, plan, change and end it, since it decides who is told what; everyone signed in sees the banner that says someone is away and how many notifications are held.
- **Buttons on notifications** (Settings → Notifications → Who hears what): switching them on is administrator-only. A link in a notification needs **no role at all** — the signed token is the access, for the alerts in that message, for 24 hours, to acknowledge, silence for an hour or snooze, and nothing else.
- **Alert rules** (Monitoring → Alert rules): everyone signed in sees the rules and where each is raised now; making, changing, trying, switching and removing one is administrator-only (a rule decides who is
woken up). **Snooze** an alert, wake it, **close** it and open it again need operator, like acknowledging. The storage forecast beside Proxmox storages and Synology volumes is for everyone who can see those pages.
- **What changed before this?** (on an incident's page, and `GET /api/v1/incidents/:id/before`): everyone signed in, like the incident record it is made from.
- **Dependencies**: everyone can see what needs what; adding and removing one needs operator. So does adding or hiding a *suggested* one.
- **To do and Notes** (Operations → To do, the *To do* and *Notes* cards on a server's page, a device's *Notes* drawer): everyone signed in reads them; adding, editing, ticking off and removing a job, and writing a note, and adding, captioning and removing a photo on one, need operator.
- **Racks** (Inventory → Racks) and the **network diagram**: everyone signed in. A rack is made from the hardware's *where* and *rack unit*, which operators edit on the inventory page.
- **Proxy hosts** (Network → Proxy hosts): everyone signed in sees what Nginx Proxy Manager serves; **Read now** needs operator; adding the integration (its login) is an administrator's job.
- **Home Assistant** (Apps → Home Assistant): everyone signed in sees what is watched, its state and history; choosing what to watch, its limits, stopping and **Read now** need operator (the list of all
entities is read live, so only operators see it); adding the integration (its token) is an administrator's job.
- **Service levels** (Monitoring → Service levels): everyone signed in sees the targets and what is left of the budget; setting, changing and removing one is administrator-only, and each is in the audit log.
- **UPS** (Monitoring → UPS): everyone signed in sees each UPS, its history and what is on it; adding one (its address and SNMP community) is an administrator's job, like any integration, and what it powers is written in the dependency map.
- **Endpoints**: everyone sees the checks and how they are doing; adding, changing and removing one is administrator-only (each makes the server connect somewhere); that includes the value a check judges and the header (a token) it sends, whose value is never shown again to anyone;
*Check now* needs operator.
- **Hetzner Cloud** (Infrastructure → Hetzner Cloud, and the card on a server's page): everyone signed in sees the servers, their addresses, traffic and cost estimate, volumes and snapshots; adding a project (its API token) is an administrator's job, like any integration. Nothing on the page changes anything at Hetzner.
- **Game servers** (Infrastructure → Game servers, Fragnet): everyone signed in sees the servers, their games, addresses, use, backups and schedules; **start, stop, restart and kill** need operator (each is written to the audit log); adding the account (its API key) is an administrator's job, like any integration.
- **Speedtest** (Monitoring → Speedtest): everyone signed in sees the speeds, their history and what is wrong; adding one (its address, an API token, and what the line is sold at) is an administrator's job, like any integration. Nothing here starts a speed test.
- **Costs** (Records → Costs): everyone signed in sees what is paid for, the estimates read from Hetzner and the totals; adding, changing and removing an item is an administrator's.
- **Nextcloud, NetBox and n8n** (Apps → Nextcloud, Network → NetBox, Automation → n8n): everyone signed in sees the status, the counts and what is wrong — for NetBox, the names and addresses of the servers that are not in it; for n8n, the names of the workflows; adding one (its address and a login, token or key) is an administrator's job, like any integration.
- **Immich** (Apps → Immich): everyone signed in sees the counts, the disk and the job queues; adding one (its address and API key) is an administrator's job, like any integration.
- **Paperless-ngx** (Apps → Paperless): everyone signed in sees the counts, the system status and the names of the files that failed to import; adding one (its address and a superuser's token) is an administrator's job, like any integration.
- **Prometheus** (Monitoring → Prometheus): everyone signed in sees the targets, what is down and the alerts firing; adding one (its address, and a token if it needs one) is an administrator's job, like any integration.
- **Authentik** (Apps → Authentik): everyone signed in sees the outposts, what runs out and the failed-sign-in count (the names of tokens and certificates, not their values); adding one (its address and API token) is an administrator's job, like any integration.
- **Jellyfin** (Apps → Jellyfin): everyone signed in sees who is streaming and what is wrong; adding one (its address and API key) is an administrator's job, like any integration. Starting an update run on a server people are streaming from needs `startAnyway` — the update drawer asks (operators).
- **Media managers** (Apps → Media managers, for Sonarr, Radarr and Prowlarr): everyone signed in sees what each says is wrong, its queue, disks and indexers; adding one (its API key) is an administrator's job, like any integration. Nothing on the page changes anything in them.
- **Duplicati** (Backups → Duplicati): everyone signed in sees every backup and how it went; setting how often one is expected, muting it and forgetting it need operator; adding a machine (which makes an address that can write to this app) and removing one are administrators'. Reports arrive on a secret address with no sign-in: the token is the access.
- **Restore tests**: everyone sees them on the Backup coverage page; recording one needs operator; removing one is administrator-only.
- **Change log**: operators and administrators (it is made from the audit log, which has the same readers).
- **Push notifications**: an administrator switches the channel on (Settings → Notifications). Each person, whatever their role, adds
and removes their own browsers and can send a test to them; an administrator can remove anyone's.
- **Backup coverage** is a read-only page for everyone. On **Updates**, everyone sees what is waiting and how update runs
are going; starting an update run (**Update…**) or stopping one needs operator.
- **Patch plans** (Updates → Patch plans) can be seen by everyone, with how they went; making, changing, switching off and removing one needs administrator (it will run on its own, at night);
**Run now** and **Stop** need operator, like an update run. The **Monthly report** page is for everyone signed in; sending it now, and its schedule (Settings), are administrators'.
**Mark as expected** on a server's Ports card (which ends a new-port alert) needs operator, like any note on a port.
- **Acknowledging an alert, handing it over, and taking it back** need operator (the person it is handed to must be an operator or
administrator); everyone sees who has what. **Incidents** (Alerts → History) are readable by everyone signed in; writing a note needs operator, and a note
can be removed by its author or an administrator.
- **Database backups** (Settings → Data → Backup: making, downloading, uploading, checking, restoring and deleting them, and the schedule) are
administrator-only: a backup holds the audit log, every server's address, the hashed agent tokens and all the stored credentials
(encrypted).
- **Alert limits** on a server's page: everyone can see the ones a server has of its own; only an administrator changes them. The same goes for the **services to
ignore** on its Host health card. Everyone sees *What the agent couldn't collect*.
- **Host health** (failed services, disk health, ZFS pools) is shown to everyone on a server's page; **Update agents automatically**
on the Servers page is admin-only.
- **Profile pictures** are shown to everyone signed in (`/api/avatars/<id>`, the same people whose names everyone already sees); which sources are allowed is under
Settings → Sign-in, so admin-only.
- **Heartbeats** and the **Coming up** list are visible to everyone signed in; only administrators see a heartbeat's address, and make, change, remove or give a new address to one, and make
the calendar feed of Coming up (a share link). **Suggested checks** are administrators' like the checks themselves. A job's call to its address needs no role: the token is the access.
- **The delivery log of an event webhook** (what was sent, with the messages, and sending one again) and **Settings → Data → Storage** (how big the app's data is) are administrator-only; sending a message again is in the audit log.
- **Sign-in groups, metrics tokens, event webhooks, share links (the wall display and the status pages, and what is on them) and the
Grafana dashboard download** are all under Settings, so admin-only; `/metrics` itself needs a metrics token, not a login.
- Everything under **Settings** (notification channels, badge colors,
display prefs, log retention, backup/restore) is admin-only, matching
the page itself being admin-only.
If you need the exact role for one specific button rather than this
summary, check the corresponding route in `server/src/routes/` — each
one that needs more than "signed in" calls `requireRole("operator")` or
`requireRole("admin")` right where that action is defined.