Files
Homelab-manager/ROLES.md
T
bobbanandClaude Sonnet 5.5 5cc51c57de Add status pages (a share link kind) and a downloadable Grafana dashboard
- 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>
2026-10-18 15:38:08 +02:00

6.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 ✅ ✅ ✅
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 /sessions ❌ ❌ ✅
Audit Log /audit-log ❌ ✅ ✅
Diagnostic Log /diag-log ❌ ❌ ✅
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, Sessions, and Diagnostic Log need admin; Audit Log needs operator or admin; Settings needs admin.

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; adding, editing and removing needs operator; the price of power used for the running cost is admin-only.
  • 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 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.
  • 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.
  • 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.