Files
Homelab-manager/ROLES.md
T
bobbanandClaude Sonnet 5.5 1432b148e9 Fold four pages into the pages they belong to; add a Backups menu group
Dependencies become a view of the Map (graph with the editor under it), Sessions the
'Signed in now' tab of Users, the Audit Log the 'Raw audit log' tab of the Change log, and the
Diagnostic Log the 'Call log' tab of Integrations (admins). Backup coverage and Proxmox Backup
move to a new Backups group. Old addresses redirect; a shared ViewTabs component does the tabs.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-19 22:21:21 +02:00

8.4 KiB

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 / ✅ ✅ ✅
Infrastructure
Servers /servers ✅ ✅ ✅
Proxmox /proxmox ✅ ✅ ✅
Synology /synology ✅ ✅ ✅
Proxmox Backup /pbs ✅ ✅ ✅
Backup coverage /backups ✅ ✅ ✅
Inventory /inventory ✅ ✅ ✅
Dependencies (Map → Dependencies) /map?view=dependencies ✅ ✅ ✅
Endpoints /endpoints ✅ ✅ ✅
Change log /changes — ✅ ✅
Docker /docker ✅ ✅ ✅
Tailscale /tailscale ✅ ✅ ✅
Network
DNS /dns ✅ ✅ ✅
Domains /domains ✅ ✅ ✅
IP Addresses /ipam ✅ ✅ ✅
Ports /ports ✅ ✅ ✅
Consistency /consistency ✅ ✅ ✅
Automation
Semaphore /semaphore ✅ ✅ ✅
Gitea /gitea ✅ ✅ ✅
Secrets /secrets ✅ ✅ ✅
Operations
Alerts /alerts ✅ ✅ ✅
Maintenance /maintenance ✅ ✅ ✅
Updates /updates ✅ ✅ ✅
Uptime Kuma /uptime-kuma ✅ ✅ ✅
osTicket /osticket ✅ ✅ ✅
Admin Links /admin-links ✅ ✅ ✅
Generator /generator ✅ ✅ ✅
Administration
Integrations /integrations ✅ ✅ ✅
Users /users ❌ ❌ ✅
Sessions (Users → Signed in now) /users?view=sessions ❌ ❌ ✅
Audit Log (Change log → Raw audit log) /changes?view=audit ❌ ✅ ✅
Diagnostic Log (Integrations → Call log) /integrations?view=calls ❌ ❌ ✅
Settings /settings ❌ ❌ ✅
Privacy (footer link, not in a group) /privacy ✅ ✅ ✅

So in practice: every page is visible to every role except the five under Administration — Users (with Signed in now) and Settings need admin; the Call log tab of Integrations needs admin (operators and viewers see Integrations without it); the raw audit log, a tab of the Change log, needs operator or admin. Sessions, the Audit Log, the Diagnostic Log and Dependencies were pages of their own once; their old addresses redirect to the sections above.

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 → Alert tickets, which is admin-only.
  • Runbooks: everyone reads them (on a server's page, an integration's card, 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.
  • Dependencies: everyone can see what needs what; adding and removing one needs operator.
  • Endpoints: everyone sees the checks and how they are doing; adding, changing and removing one is administrator-only (each makes the server connect somewhere); Check now needs operator.
  • 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.
  • 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 → 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.
  • 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.